typ: dc+sd-jwt) signed by Baselayer’s issuer, https://registry.baselayer.com. The agent always adds its own signature over a one-time nonce from the site, so a copied credential is useless to anyone else.
Before you start
- The agent needs its own Ed25519 key pair. The private key stays with the agent.
- Your backend sends only the public key to Baselayer when it mints, as
agent_key. - Minting needs your Baselayer API key, so it runs on your backend.
Present the credential
These are the six steps the agent runs. You can build them in any language. The agent makes its own Ed25519 key pair first. For example, in Node:1
Discover
The agent requests a protected page with no credential. The site answers The
401 with a step-up that names what it needs:requirement lists the fields the credential’s checks must back (required_fields), the keys those fields need (required_keys), and, in fields, the exact details the site may read. Mint with only those details. The site refuses extra ones as scope_violation.2
Get a nonce
The agent calls the site’s nonce endpoint:The response carries a single-use nonce and, usually, the audience the site will check:
3
Mint
Your backend mints a credential with
audience set to that audience and agent_key set to the agent’s public key.In the mint response, credentials[0].credential is a string that ends in ~. The empty slot after the last ~ is where the agent’s signature goes.4
Sign
The agent signs a Key Binding JWT and appends it to the credential:
The result is
<credential><Key Binding JWT>, signed with the private key that matches the credential’s cnf key.5
Exchange
The agent posts the presentation to the site’s token endpoint as an OAuth 2.0 token exchange (RFC 8693):
scope is the scope of the requirement from step 1, when it named one.The site checks the presentation and, if it passes, answers with its own token (access_token, token_type, expires_in).6
Use the token
The agent uses the site’s token on later requests.
- When
token_typeisDPoP, each request also carries a DPoP proof signed with the same agent key, so the token only works for this agent. - When the token expires, the agent runs the flow again with a freshly minted credential.
nonce_replayed, and one it never issued (or that expired) as nonce_not_issued.Acting for a business
A business is presented as two credentials minted together: the business credential and the acting person’s own credential. The agent signs a separate Key Binding JWT for each, with the same nonce and audience, and sends the business one assubject_token and the person’s as actor_token:
Implementation rules
- Keep the agent’s private key with the agent.
- Use one key per agent. A site can recognize an agent by the thumbprint of its
cnfkey. - Mint a fresh credential for each session. Credentials are short-lived on purpose.
- Use the audience the site’s nonce endpoint returns, both in the mint and in the Key Binding JWT.
Rotate an agent key
- Generate a new key pair for the agent.
- Mint new credentials with the new public key as
agent_key. - Revoke the active credentials minted for the old key. Use the reason
agent_key_compromisewhen the old key may have leaked. See Managing and Revoking Credentials.
Troubleshooting
For every refusal code and the check it comes from, see Order of checks in the Credential Format Reference.
Next steps
- Managing and Revoking Credentials: find a credential you minted and revoke it.
- KYA Sandbox and Testing: test the full flow with test data.