airService.verifyCredential(...) against an SD_JWT_VC verification program and the result drives anything on your side, such as account upgrades, access, or payouts.
AIR checks the presentation before it returns Compliant, but that check runs in the user’s browser. Send the presentation to your backend and verify it there.
What you receive
ACompliant result carries a W3C Verifiable Presentation. For SD_JWT_VC programs it wraps one compact SD-JWT inside an EnvelopedVerifiableCredential:
Non-Compliant, NotFound) carry no presentation.
Holder key binding
Holder binding stops a leaked credential from being presented by someone else: presenting it with a valid KB-JWT also takes the holder’s private signing key.- At issuance, the user’s AIR Account provides a P-256 signing public key, and the issuer writes it to the credential’s
cnf.jwkclaim. This happens on both issuance paths: in SDK issuance AIR sends the key to the issuer assigningKey.jwk, and in direct issuanceinitialize-userreturns it assigningKey. - At verification, you choose whether to require proof of possession. Send a
nonce(recommended), and the holder signs a key-binding JWT (KB-JWT) with the matching private key. It covers yournonce, yourprogramId, the signing time, and a hash of the disclosed claims, so it cannot be reused or edited.
- You passed a
noncetoverifyCredential. - The credential’s issuer JWT contains a holder key in
cnf.jwk(EC P-256).
aud is always the programId you passed.
Without a KB-JWT the token is a bearer presentation: if it leaks through logs, proxies, or a malicious script on the page, someone else can submit it as their own. Holder binding only protects you if you ask for it and check it, so send a nonce and require the KB-JWT.
Recommended flow
1
Create a nonce on your backend
Generate at least 128 bits of randomness, for example
crypto.randomBytes(16).toString("base64url"), and store it against the user’s session.2
Pass it to verifyCredential
3
Send the presentation to your backend
On
Compliant, post result.verifiablePresentation to your backend.4
Consume the nonce, then verify
Read the user’s nonce and delete it in the same step, then run the checks below against it. Each nonce is checked once: two submissions of the same presentation cannot both pass, and after a failed check the user starts a new verification.
Token anatomy
The compact token is~-separated:
verifiableCredential[0].id and strip the data:application/dc+sd-jwt, prefix. Older results may use data:application/vc+sd-jwt,; accept both.
Issuer JWT. Signed by the credential issuer. The payload carries the always-visible claims, plus _sd digests for the selectively disclosable ones:
sub is the holder DID. The credential’s own nonce is the issuer’s revocation nonce, which you use for revocation status; it is unrelated to the nonce you pass for the KB-JWT. AIR issuance always sets cnf, and status appears only when the issuer publishes a token status list.
Disclosures. Each is base64url-encoded JSON such as ["<salt>", "given_name", "Ada"]. A disclosure is valid only if its SHA-256 digest appears in an _sd array of the signed payload. The token contains only the disclosures for the fields you requested; the others stay hidden behind their digests.
KB-JWT. Signed by the holder’s key from cnf.jwk:
sd_hash is the base64url SHA-256 of everything before the KB-JWT, including the trailing ~. It locks the set of disclosures, so nobody can add or remove one after the holder signed.
Inspect a presentation
To see what your backend actually receives, decode a sandbox presentation by hand. This shows which claims the holder disclosed and which stay hidden. It does not verify anything: anyone can decode the token, and only the checks below make its claims trustworthy.1
Run a verification in sandbox
Log in with a user who holds the credential, call
verifyCredential with a nonce, and approve sharing in the AIR window.2
Copy the presentation
In your browser’s developer tools, open Network, select the request that posts
verifiablePresentation to your backend, and copy its payload to presentation.json. Copying it from the request means you don’t add logging to your app.3
Decode it
Save this as This script handles only top-level claims. Nested claims (
inspect-sd-jwt.mjs and run node inspect-sd-jwt.mjs presentation.json. It needs no dependencies.address.city) have their own _sd arrays inside the disclosed values.tier, member_since, and over_18, verified with fieldsToDisclose: ["tier", "over_18"], the output looks like this:
member_since is not in the token at all. The issuer JWT contains only its digest, so the verifier cannot learn its value.
Checks
Always
-
Issuer is trusted.
issis on your allowlist. Choose the issuer’s key source from your own configuration, never from a URL taken from the token. -
Issuer signature is valid, using the issuer’s keys:
did:webissuer: fetch the DID document.did:web:issuer.exampleresolves tohttps://issuer.example/.well-known/did.json, anddid:web:issuer.example:pathtohttps://issuer.example/path/did.json. Use thepublicKeyJwkof itsassertionMethodentries. The JWT headerkidis the full DID URL (did:web:issuer.example#key-1); older credentials carry only the fragment (key-1).- HTTPS issuer: fetch the issuer metadata from
/.well-known/jwt-vc-issuer, inserted between the host and any path (https://issuer.example/tenantresolves tohttps://issuer.example/.well-known/jwt-vc-issuer/tenant). Itsissuermust equaliss. Use itsjwks, or the keys at itsjwks_uri. - Any other issuer id: use the issuing partner’s JWKS URL registered in the Developer Dashboard.
kidagainst each key’skidin full, or by the part after#: current credentials use the full DID URL, while JWKS keys usually carry only the fragment. -
Disclosures are genuine.
_sd_algissha-256, and every disclosure’s digest appears in the signed payload. -
Credential is in date.
exphas not passed, andnbf(if present) has. -
Credential type is right.
vctequals the type you expect. -
You got what you asked for. Every field in your
fieldsToDiscloseis present among the verified claims. - Optional: not revoked. See Revocation.
Additionally, when a KB-JWT is expected
Expect a KB-JWT whenever you sent a nonce and the issuer JWT hascnf.jwk.
- KB-JWT is present. If it is missing, reject: someone stripped the binding.
- Header is
typ: kb+jwtwithalg: ES256. - Signature verifies against the issuer JWT’s
cnf.jwk. nonceequals the nonce you issued for this session. Delete the nonce when you read it, before this check, so it is used once.audequals yourprogramId.iatis recent: no older than your freshness window (for example 5 minutes), and not in the future beyond a small clock-skew allowance (for example 60 seconds).sd_hashequals the base64url SHA-256 of the token up to and including the~before the KB-JWT.
Decision table
A KB-JWT whose
nonce, aud, signature, or sd_hash does not match is always a rejection.
Reference implementation
- The library checks the KB-JWT’s
typ, signature,nonce, andsd_hash, but notaudor how oldiatis. The function checks those itself. - The library ignores the KB-JWT entirely unless you pass
keyBindingNonce. The function passes it whenever a KB-JWT is expected, so a stripped KB-JWT fails withKey Binding JWT not exist.
verify-air-sd-jwt.ts
claims holds every verified claim: the always-visible ones (iss, vct, cnf, and so on) plus the disclosed fields, with nested fields as nested objects (claims.address.city). Undisclosed fields are absent. holderBound tells you whether a KB-JWT was verified.
Any failure throws, so treat an exception as “not verified”.
Revocation
AIR checks revocation duringverifyCredential only when the verification program enables issuer revocation checks. To check it on your backend, or again when you re-verify a stored presentation, use one of the issuer’s two sources.
Per credential. AIR issuers answer GET /revocation-status/:nonce with { "isRevoked": boolean }, where :nonce is the always-visible nonce claim in the issuer JWT. Set revocationStatusUrl on the trusted issuer to the issuer’s revocationStatusApiUrl, without the /:nonce part. The function then rejects the credential unless the response is { "isRevoked": false }, and also rejects if the request fails. See Revoke credentials.
Token Status List. Credentials whose issuer publishes an IETF Token Status List carry status.status_list.{uri, idx} in the issuer JWT. Pass checkStatus: true, and the library:
- Fetches
uriwithAccept: application/statuslist+jwt. The response must use that content type. - Verifies the status-list JWT with the same issuer keys.
- Rejects the credential if the entry at
idxis not0(valid).
checkStatus does nothing for credentials without status, such as those issued before the issuer enabled the list. Use revocationStatusUrl for those.
Troubleshooting
References
- Selective Disclosure for JWTs (SD-JWT): token format, disclosures, KB-JWT,
sd_hash. - SD-JWT-based Verifiable Credentials (SD-JWT VC):
vct,cnf,status,dc+sd-jwtmedia type. - Token Status List: revocation.
- VC Data Model 2.0: Enveloped Verifiable Credentials: the
data:URL wrapper. - did:web method: resolving
did:webissuers.