Skip to main content
This page is for teams that parse and verify KYA credentials in their own code. KYA credentials follow published standards: SD-JWT VC (draft-ietf-oauth-sd-jwt-vc-19) over Selective Disclosure for JWTs (RFC 9901), with revocation through OAuth Token Status Lists (draft-ietf-oauth-status-list-21).

Encoding

A presentation is one issuer-signed JWT, its Disclosures, and the agent’s Key Binding JWT, joined with ~:
The mint returns everything up to and including the last ~. The agent appends the Key Binding JWT when it presents. The issuer JWT header:
  • typ is always dc+sd-jwt. Refuse anything else.
  • alg is always EdDSA, over an Ed25519 key (kty: OKP, crv: Ed25519).
  • kid is 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 only email 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, actor and business Disclosures.
  • Each credential has its own jti and status.
  • They share one aud, one cnf key 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.example becomes https%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.
Key your returning-customer records on 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. Read active_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.sub equals the sub of the person’s individual credential at the same audience.
  • authorization.status is always verified. Baselayer mints a business credential only with a verified operator link.
  • method is evidence when the automatic checks verified the link, or reviewer when the minting organization decided it.
  • confirmed_at is when the link was last confirmed.
When verifying a business pair, require:
  • The same iss.
  • The same aud.
  • The same cnf key.
  • The same nonce in both Key Binding JWTs.
  • actor.sub equal to the person credential’s sub.
  • actor.authorization.status equal to verified.
Refuse a business credential presented without the person’s credential.

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 _sd array. For example, address.locality is disclosed by an address Disclosure whose value is an object with its own _sd, plus a locality Disclosure inside it.
  • Each non-empty _sd array also holds zero to three decoy digests that match no Disclosure.
To check for tampering:
  1. For each Disclosure, compute base64url(SHA-256(<the Disclosure exactly as received>)).
  2. Confirm it appears in exactly one _sd array: in the payload, or in an object already disclosed.
  3. If any digest is missing, refuse the whole presentation (disclosure_digest_mismatch).
Digests with no matching Disclosure are decoys or details that were not shared, and are ignored. Detail paths, as dotted paths over the rebuilt claims. Asking for Fields lists the same paths in plain words. Individual paths
  • 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
Business paths
  • 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
Notes on values:
  • Instants are seconds since the epoch. birthdate and date_of_incorporation are ISO 8601 dates.
  • age_birth_year is a year. age_over_18 and age_over_21 are true or false, worked out when the credential is minted.
  • hashes.* values are sha256:<hex> over a normalized form of the verified value.
  • Business structure is lowercase, for example llc.
  • registration_status is active, inactive or dissolved.
  • address.address_type is registered, mailing, physical or residential.
  • Business domain is the registrable domain of the business’s website, in punycode form for internationalized names.
  • On a business credential, legal_name, email and address are 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:
See the API reference.
  • Require issuer to equal the credential’s iss.
  • Pick the key whose kid matches the JWT header.
  • Decide the issuer before you fetch anything. Refuse an iss you do not trust without making a request.
  • Cache per Cache-Control (one hour). On an unknown kid, 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.
The same keys are also served as a JWKS at <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.
See the API reference. The response is a JWT with typ: statuslist+jwt and content type application/statuslist+jwt, signed with the same issuer keys. Its claims: To check a credential:
  1. Decode lst (base64url without padding).
  2. Decompress it with zlib.
  3. Read bit idx: byte idx // 8, bit idx % 8, least significant bit first. 1 means revoked.
Each list holds 1,048,576 bits. Accept the token only inside its window: 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.sub is actor_mismatch.
  • A different cnf key or nonce is key_binding_invalid.
  • An unverified link is actor_not_authorized.
Spend the nonce only after every check passes. These are the same codes Agent Acceptance reports. Handling Failures says what to tell the agent for each.