Encoding
A presentation is one issuer-signed JWT, its Disclosures, and the agent’s Key Binding JWT, joined with~:
~. The agent appends the Key Binding JWT when it presents.
The issuer JWT header:
typis alwaysdc+sd-jwt. Refuse anything else.algis alwaysEdDSA, over an Ed25519 key (kty: OKP,crv: Ed25519).kidis the RFC 7638 thumbprint of the signing key, published in the issuer’s key set.
Claims
Ignore top-level claims you do not recognize, so future additions never break your verifier.
The issuer JWT payload of a person’s credential that shares details (an L3 credential) looks like this:
What each credential carries
The fields you mint with set what is shared. A person’s credential that shares onlyemail and phone_number, or nothing, is an L2 credential. Any other field makes it L3. A business credential is always L3.
Business credentials
- The business credential carries the standard claims,
verification,actorand business Disclosures. - Each credential has its own
jtiandstatus. - They share one
aud, onecnfkey and one validity window.
Subject
sub is a per-site ID:
<audience>is the canonical audience, percent-encoded. A bare host stays as is.https://shop.examplebecomeshttps%3A%2F%2Fshop.example.<suffix>is 32 lowercase hex characters. It is the same for the same person (or business) at the same audience across every mint, and unrelated across audiences.
sub, never on jti. A jti is new on every mint.
The verification block
The verification block says which checks passed when Baselayer verified the person or business. Readactive_keys for policy.
Each key’s
basis is verified when Baselayer verified it, or attested when the platform that verified the person vouched for it. time is the UTC day the check was established, in seconds since the epoch.
active_keys values on an individual credential:
active_keys values on a business credential:
ssn_identity_match, and the ssn_last_4 and hashes.ssn paths below, are filled in by Baselayer from its own verification. In Baselayer’s flow the person never types an SSN: they enter their phone, birthday and country, type the code Baselayer texts them, and confirm the details shown.
The credential carries no level. Sites ask for keys, and a verifier checks the keys a credential holds. A business credential needs registry_record_found, tax_id_match and registration_active, and its acting person needs phone_possession or email_possession. A verifier refuses a business credential, or a business pair’s person, that lacks them (required_keys_missing).
The actor block
Every business credential carries:actor.subequals thesubof the person’s individual credential at the same audience.authorization.statusis alwaysverified. Baselayer mints a business credential only with a verified operator link.methodisevidencewhen the automatic checks verified the link, orreviewerwhen the minting organization decided it.confirmed_atis when the link was last confirmed.
- The same
iss. - The same
aud. - The same
cnfkey. - The same nonce in both Key Binding JWTs.
actor.subequal to the person credential’ssub.actor.authorization.statusequal toverified.
Disclosures
Each Disclosure is base64url of a JSON array[salt, claim_name, claim_value]. claim_name is the claim’s own name, never a dotted path. Salts are 128 bits.
Disclosure is nested.
- Any object with selectively disclosed members has its own
_sdarray. For example,address.localityis disclosed by anaddressDisclosure whose value is an object with its own_sd, plus alocalityDisclosure inside it. - Each non-empty
_sdarray also holds zero to three decoy digests that match no Disclosure.
- For each Disclosure, compute
base64url(SHA-256(<the Disclosure exactly as received>)). - Confirm it appears in exactly one
_sdarray: in the payload, or in an object already disclosed. - If any digest is missing, refuse the whole presentation (
disclosure_digest_mismatch).
- Name:
given_name,middle_name,family_name,name - Contact:
email,phone_number - Address:
address.street_address,address.locality,address.region,address.postal_code,address.country,address.usps_validated - Birth and identity:
birthdate,age_birth_year,age_over_18,age_over_21,ssn_last_4 - Hashes:
hashes.name,hashes.email,hashes.phone_number,hashes.address,hashes.ssn
- Identity:
legal_name,dbas,ein,structure - Incorporation:
state_of_incorporation,country_of_incorporation,date_of_incorporation - Address:
address.street_address,address.locality,address.region,address.postal_code,address.country,address.address_type - Contact and web:
email,website,domain - Status:
registration_status - Hashes:
hashes.name,hashes.ein,hashes.email,hashes.address
- Instants are seconds since the epoch.
birthdateanddate_of_incorporationare ISO 8601 dates. age_birth_yearis a year.age_over_18andage_over_21aretrueorfalse, worked out when the credential is minted.hashes.*values aresha256:<hex>over a normalized form of the verified value.- Business
structureis lowercase, for examplellc. registration_statusisactive,inactiveordissolved.address.address_typeisregistered,mailing,physicalorresidential.- Business
domainis the registrable domain of the business’s website, in punycode form for internationalized names. - On a business credential,
legal_name,emailandaddressare the business’s. The person’s details are in the person’s own credential.
Credential types
Sandbox credentials carry the same
vct URLs. Each URL serves the type’s metadata (display labels for each claim). Fetching it is optional. Verification never depends on it.
Audience
aud takes one of two forms, and you compare it to your own audience as an exact string:
The two forms never merge.
shop.example, www.shop.example and https://shop.example are three different audiences, each with its own sub.
Issuer keys
Find the signing keys from the issuer’s metadata:- Require
issuerto equal the credential’siss. - Pick the key whose
kidmatches the JWT header. - Decide the issuer before you fetch anything. Refuse an
issyou do not trust without making a request. - Cache per
Cache-Control(one hour). On an unknownkid, refetch once, then refuse. - During a key rotation, the old key stays published beside the new one, so credentials it signed keep verifying until they expire.
<iss>/.well-known/jwks.json and as a DID document at <iss>/.well-known/did.json, for tools that expect those. All three are public, need no API key, and can be cached for an hour.
Status list
status.status_list.uri points to a signed status list, for example https://registry.baselayer.com/statuslists/1.
- Each issuer fills list 1, then list 2, and so on.
- A list that has not been started returns
404.
typ: statuslist+jwt and content type application/statuslist+jwt, signed with the same issuer keys. Its claims:
To check a credential:
- Decode
lst(base64url without padding). - Decompress it with zlib.
- Read bit
idx: byteidx // 8, bitidx % 8, least significant bit first.1means revoked.
iat no more than 300 seconds ahead, exp in the future, and now earlier than iat + ttl. Cache it until min(exp, iat + ttl). If the list cannot be fetched or does not verify, refuse the presentation.
The list is shared by many credentials from the issuer, so fetching it doesn’t identify which credential you are checking.
Key Binding JWT
It must verify against the credential’s
cnf.jwk.
Order of checks
Run these in order on each credential, and refuse at the first failure:
On a business pair, run both credentials through these checks, then the pair checks from The actor block:
- A different issuer or
actor.subisactor_mismatch. - A different
cnfkey or nonce iskey_binding_invalid. - An unverified link is
actor_not_authorized.