Skip to main content
This page covers the agent’s side: how an agent shows its credential to a site. For the site’s side, see the Credential Format Reference to check the credential and Accepting Agents at Your Site to decide what the agent may do. A KYA credential is an SD-JWT VC (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.
See Minting Credentials.

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 401 with a step-up that names what it needs:
The 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_type is DPoP, 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.
Each nonce works once. A site refuses a reused nonce as 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 as subject_token and the person’s as actor_token:
The site accepts or refuses the pair as one. A business credential sent without the person’s credential is refused. See Business Agents.

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 cnf key.
  • 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

  1. Generate a new key pair for the agent.
  2. Mint new credentials with the new public key as agent_key.
  3. Revoke the active credentials minted for the old key. Use the reason agent_key_compromise when 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