What happens when an agent arrives
Agents that carry a KYA credential find your setup on their own. The KYA SDK on the agent’s side knows where to look.1
The agent learns what you ask for
It gets your
401, reads your kya-profile.json, and gets a credential minted for your site with only those fields.2
The agent presents its credential
It asks your nonce route for a single-use code, then sends its credential to your token route with a short proof signed by its own key. The proof includes your nonce and your domain, so it only works once and only at your site.
3
Your code verifies it
The SDK checks that Baselayer issued the credential, that it was issued for your site, that it hasn’t expired or been revoked, that the shared fields haven’t been changed, that it’s being shown by the agent it was issued to, and that the nonce is yours and unused.
4
Your policy decides
You get a pass with the fields below, or a typed reason for the failure. On a pass, you give the agent your usual access token and decide what it may do.
What you get
When a credential passes,report.exchangeClaims() gives you four things. The examples below call it claims.
A customer ID
claims.sub is stable for the same customer at your site. Another site gets a different ID for the same person. To know a returning customer, look this ID up in your own records (see Matching customers).
The checks that passed
claims.verification.active_keys lists what Baselayer verified, such as a confirmed phone (phone_possession), a matched date of birth (dob_identity_match) or a clear watchlist result (watchlist_clear). See the verification block for what each check means.
The fields your profile requested
claims.claims contains only the fields listed in the scope you asked for, never more. A field can be absent when Baselayer has no value for it, so check that the fields you need are present before relying on them. report.credential.disclosed has the same fields as { path: value }.
An expiry
claims.exp tells you when the credential expires. Don’t issue a session that outlives it.
Setting your own rules
The SDK tells you what is true about the credential. It never tells you to let an agent in or keep it out. You might:- Let any verified customer browse.
- Require a clear watchlist result (
claims.attests("watchlist_clear")) before checkout. - Let a returning customer reorder without signing in.
What Baselayer sees
The check runs in your own backend, login server or edge worker. To check a credential, the SDK uses two public files from Baselayer: the keys used to sign credentials and the list of revoked credentials. Both are cached. The revocation list is shared by many credentials, so fetching it doesn’t identify which customer or credential you are checking. What you decide stays in your own code.Set it up
The KYA SDK is coming soon. The install commands won’t work until the packages are published. Until then, you can check credentials yourself with the Credential Format Reference.
1
Install the SDK
npm install @baselayer/kya or pip install baselayer-kya (coming soon, not published yet).2
Publish your profile
Host a
kya-profile.json at /.well-known/kya-profile.json listing the fields you ask for at each step. See Asking for fields.3
Add two routes
Add a nonce route (
POST /nonces) and a token route (POST /oauth/token). Answer a protected page with no token with 401 and a KYA-Disclosure-Scope header.4
Verify and decide
In the token route, call
verifier.verify() with the scope from your published profile, apply your rules, and return your token or the failure code.Next steps
- SDK quickstart: install the SDK and check your first credential.
- Asking for fields: publish the fields you need at each step.
- Where to run it: your backend, your login server or the edge.