Skip to main content
For agent platforms, and businesses running their own agents, that give agents credentials for the people and businesses they verified. Once a person or business is verified, you can mint a credential for their agent. A credential is minted on demand, scoped to one site (its audience) and bound to one agent’s public key. A stolen credential is useless without the agent’s private key.
Before you startYou need:
  • An individual_ref for a person with an accepted verification. See Verifying an Identity.
  • The agent’s Ed25519 public key. The agent generates its own key pair. Baselayer only ever sees the public key.
  • For a business credential, also a business_ref and a verified operator link between the two. See Who Can Act for a Business.

Where the fields come from

The site decides what a credential shares:
  1. The site’s rules name the fields for each step, as a scope.
  2. The site answers an agent with 401 and a step-up. Its requirement carries the scope’s fields.
  3. You copy those fields into disclosed_fields. For a business, the person’s fields go in actor_disclosed_fields.
  4. Baselayer mints only those fields, never more. The site refuses a credential that carries more.
  5. Every field must be one the person’s record can back: proved by a check they passed and on file. Otherwise the mint is refused and nothing is minted.
To see exactly which fields a mint will carry, preview it first.
For every field in plain words, see Fields a scope can list.

Presets

Instead of listing fields, a mint can name a preset: a named set of fields. Use one when it matches the site’s scope exactly, since a site refuses extra fields as scope_violation. Every field in a preset must be backed, the same as a listed field. If one isn’t, the whole mint is refused. A mint through the API applies no preset unless it names one. A mint that names no preset and lists no fields shares no details beyond the checks that passed. To get the same list in code, call:
See the API reference.
  • The list is the same for everyone and can be cached for an hour.
  • Each preset lists the exact paths it requests on an individual mint and on a business mint.
  • is_individual_default and is_business_default mark the most conservative preset for each case (consumer_ecommerce and b2b_ecommerce), which the console preselects.

Mint an individual credential

POST /issuance/credentials with type: individual mints for a verified person acting as themselves. Every credential shares the customer ID for this site and the checks that passed. The same person gets the same ID at the same site every time, across agents, keys and sessions. At a different site they get a different ID. It also shares the fields the site’s scope lists, sent as disclosed_fields or a matching preset. A mint that shares only email and phone_number, or nothing, makes an L2 credential. Any other field makes it L3. You don’t choose the level: it follows the fields. A path outside the schema is a 422 (6302).
Send every mint with an Idempotency-Key header. A retry with the same key and body within 24 hours returns the first response, marked Idempotent-Replayed: true, instead of minting again. Write audience as a bare domain (shop.example) or an https address with no path (https://shop.example). Queries, fragments and ports other than 443 are refused too. The site is matched exactly. shop.example and https://shop.example are two different audiences, and so are shop.example and www.shop.example. Each gets its own per-site ID. See every body field in the API Reference. The response lists the minted credentials in credentials, subject first:
  • credential is the string to hand the agent, ending in ~.
  • credential_id is the credential’s ID, the same as the jti inside it. Use it to look up or revoke the credential.
  • role is subject, or actor for the person’s credential on a business mint.
  • ttl_capped is true when the evidence behind the credential shortened the lifetime you asked for.
The response has no expiry time. Read the token’s exp, or the credential’s record at GET /issuance/credentials/{credential_id}, which also lists its disclosed_fields and active_keys. To set how long a credential works, send ttl_seconds with the mint. Without it, a credential works for one hour (3600). The maximum is 24 hours (86400), and a credential never outlasts the evidence behind it.

Mint a business credential

POST /issuance/credentials with type: business takes the individual body plus business_ref. It requires a verified operator link between the person and the business. Anything else is a 409 (6300). A business credential is always L3. The business must hold registry_record_found, tax_id_match and registration_active, and the person phone_possession or email_possession, or the mint is a 409 (6332) whose metadata.missing_keys lists what is missing. The response has two entries in credentials:
  • role: subject for the business, with the business paths from disclosed_fields.
  • role: actor for the person, with the paths from actor_disclosed_fields.
Each has its own credential_id. The agent presents both together. The rest of the body is the same as the individual example. Only these fields change:

Preview a mint

Send the same body to the preview endpoint:
See the API reference. agent_key is optional and unused there. A preview runs the same checks and refusals as a mint, and signs, stores and allocates nothing. The preview returns environment, ttl_capped and one entry in credentials per credential the mint would produce. Each entry shows:
  • disclosed: exactly what the mint would share, each with path, value and hashed.
  • expires_at: when a mint now would expire.
  • active_keys: the checks that would pass, each with its basis and time.
  • authorization: on a business preview, the subject entry also has the operator authorization.
A field the record can’t back is refused here with the same 422 (6333) as the mint.

Test credentials

See the API reference for test mints and test previews. These two endpoints take the same body and mint (or preview) the same credential, signed by the sandbox issuer and recorded in your sandbox application. They work from a production key too. See Sandbox and Testing.

Readable values or hashes

List a field’s own path, such as email, to share its readable value. List its hashes. path, such as hashes.email, to share only a hash the site can match against its own records. For how each field maps to its hash, see Asking for Fields. For how the credential is signed and checked, see the Credential Format Reference.

Troubleshooting

Request problems

Environment problems

Next steps