Before you startYou need:
- An
individual_reffor 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_refand averifiedoperator link between the two. See Who Can Act for a Business.
Where the fields come from
The site decides what a credential shares:- The site’s rules name the fields for each step, as a scope.
- The site answers an agent with
401and a step-up. Itsrequirementcarries the scope’sfields. - You copy those
fieldsintodisclosed_fields. For a business, the person’s fields go inactor_disclosed_fields. - Baselayer mints only those fields, never more. The site refuses a credential that carries more.
- 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.
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 asscope_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:
- 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_defaultandis_business_defaultmark the most conservative preset for each case (consumer_ecommerceandb2b_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).
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:
credentialis the string to hand the agent, ending in~.credential_idis the credential’s ID, the same as thejtiinside it. Use it to look up or revoke the credential.roleissubject, oractorfor the person’s credential on a business mint.ttl_cappedistruewhen the evidence behind the credential shortened the lifetime you asked for.
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: subjectfor the business, with the business paths fromdisclosed_fields.role: actorfor the person, with the paths fromactor_disclosed_fields.
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: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 withpath,valueandhashed.expires_at: when a mint now would expire.active_keys: the checks that would pass, each with itsbasisandtime.authorization: on a business preview, the subject entry also has the operator authorization.
422 (6333) as the mint.
Test credentials
Readable values or hashes
List a field’s own path, such asemail, 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
Identity or link problems
Environment problems
Next steps
- Presenting a Credential: have the agent show its credential to the site.
- Managing and Revoking Credentials: find a credential you minted and revoke it.