Skip to main content
Use this guide when you call 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

A Compliant result carries a W3C Verifiable Presentation. For SD_JWT_VC programs it wraps one compact SD-JWT inside an EnvelopedVerifiableCredential:
The presentation wrapper, including holder, is not signed. Only the compact SD-JWT inside id is. Everything you trust must come from that token.
Other statuses (i.e. 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.jwk claim. This happens on both issuance paths: in SDK issuance AIR sends the key to the issuer as signingKey.jwk, and in direct issuance initialize-user returns it as signingKey.
  • 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 your nonce, your programId, the signing time, and a hash of the disclosed claims, so it cannot be reused or edited.
AIR attaches a KB-JWT only when both of these are true:
  1. You passed a nonce to verifyCredential.
  2. The credential’s issuer JWT contains a holder key in cnf.jwk (EC P-256).
The KB-JWT’s 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.
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:
To get it, take 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 inspect-sd-jwt.mjs and run node inspect-sd-jwt.mjs presentation.json. It needs no dependencies.
This script handles only top-level claims. Nested claims (address.city) have their own _sd arrays inside the disclosed values.
For a credential with 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.
Disclosures are personal data. Inspect sandbox presentations only, delete the file when you are done, and never log production tokens.

Checks

Always

  1. Issuer is trusted. iss is on your allowlist. Choose the issuer’s key source from your own configuration, never from a URL taken from the token.
  2. Issuer signature is valid, using the issuer’s keys:
    • did:web issuer: fetch the DID document. did:web:issuer.example resolves to https://issuer.example/.well-known/did.json, and did:web:issuer.example:path to https://issuer.example/path/did.json. Use the publicKeyJwk of its assertionMethod entries. The JWT header kid is 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/tenant resolves to https://issuer.example/.well-known/jwt-vc-issuer/tenant). Its issuer must equal iss. Use its jwks, or the keys at its jwks_uri.
    • Any other issuer id: use the issuing partner’s JWKS URL registered in the Developer Dashboard.
    Match the header kid against each key’s kid in full, or by the part after #: current credentials use the full DID URL, while JWKS keys usually carry only the fragment.
  3. Disclosures are genuine. _sd_alg is sha-256, and every disclosure’s digest appears in the signed payload.
  4. Credential is in date. exp has not passed, and nbf (if present) has.
  5. Credential type is right. vct equals the type you expect.
  6. You got what you asked for. Every field in your fieldsToDisclose is present among the verified claims.
  7. 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 has cnf.jwk.
  1. KB-JWT is present. If it is missing, reject: someone stripped the binding.
  2. Header is typ: kb+jwt with alg: ES256.
  3. Signature verifies against the issuer JWT’s cnf.jwk.
  4. nonce equals the nonce you issued for this session. Delete the nonce when you read it, before this check, so it is used once.
  5. aud equals your programId.
  6. iat is 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).
  7. sd_hash equals 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 code works around two library behaviors:
  • The library checks the KB-JWT’s typ, signature, nonce, and sd_hash, but not aud or how old iat is. 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 with Key Binding JWT not exist.
verify-air-sd-jwt.ts
Usage on your backend:
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 during verifyCredential 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:
  1. Fetches uri with Accept: application/statuslist+jwt. The response must use that content type.
  2. Verifies the status-list JWT with the same issuer keys.
  3. Rejects the credential if the entry at idx is not 0 (valid).
checkStatus does nothing for credentials without status, such as those issued before the issuer enabled the list. Use revocationStatusUrl for those.

Troubleshooting

References