Skip to content

Terminology

Vocabulary used throughout this section.

The roles

Issuer : The organization that creates and signs a credential, asserting something about the holder. A school issuing a student card. You run a credential issuance service to do this.

Holder : The person a credential is about, who keeps it and decides when to share it. Holders interact with the system through a wallet.

Verifier : The party that asks a holder for a credential and checks it. A bookshop confirming student status. Also called a relying party. You run a credential verification service to do this.

Wallet : The holder's own application, holding their credentials and assembling presentations on request. Usually a phone app; see Wallet.

Credentials and presentations

Verifiable credential (VC) : A tamper-evident set of claims about a holder, signed by an issuer. This is what the holder stores.

Verifiable presentation : What a holder sends to a verifier. Assembled per request, signed by the wallet, and containing only the claims the holder approved. A credential is stored; a presentation is produced.

Claim : A single statement inside a credential — first_name, dateOfBirth. Claims are addressed by a path, an array of keys, e.g. ["credentialSubject", "first_name"].

Selective disclosure : Revealing some of a credential's claims and withholding the rest, without invalidating the issuer's signature. Implemented with SD-JWT.

Zero-knowledge proof : Proving a statement about a claim without revealing the claim — that a holder is over 18, without disclosing their date of birth.

Credential configuration : An issuer-side declaration of something the service is able to issue: the format, the claim paths, and how a wallet should display it. Every issuance names one. See Credential configurations.

Credential dataset : The actual claim values supplied when starting an issuance, nested under a credentialSubject key. The configuration says what the shape is; the dataset fills it in.

Holder binding : Cryptographically tying a credential to the wallet it was issued to, so a copy obtained by someone else cannot be presented. Optional, and requested per credential with require_cryptographic_holder_binding in a DCQL query.

did:jwk : A DID method that encodes a public key directly in the identifier, rather than pointing at a record to look up. The holder's wallet key appears this way in a credential's sub claim.

Formats and protocols

SD-JWT : Selective Disclosure JSON Web Token. The credential format used by default. The signed payload contains hashes of the claims (_sd), with the values themselves appended after the signature as ~-separated disclosures — so the holder can send some and withhold others while the signature stays valid.

mdoc : The ISO/IEC 18013-5 mobile document format, originally for driving licenses. Verified alongside SD-JWT; both have their certificate chains validated against your trust anchors — see Trust model.

OID4VCI : OpenID for Verifiable Credential Issuance. The protocol by which a wallet collects a credential from an issuer. See OID4VCI issuance protocol.

OID4VP : OpenID for Verifiable Presentations. The protocol by which a verifier requests, and a wallet submits, a presentation. See OID4VP presentation protocol.

DCQL : Digital Credentials Query Language, part of OID4VP. How a verifier states which credentials and which claims it wants. A DCQL query is the query object itself; it is carried inside a verification query rather than being created on its own. See Verification queries.

Verification query : The reusable object a verifier creates to hold a DCQL query, together with the uri_prefix used for sessions started from it. Addressed by verification_query_id, which is the one required field when you request a presentation. Created once and reused across sessions.

Trust

Trust anchor : A root certificate a verifier is willing to trace an issuer back to. Configured as a directory of *.pem files, deciding which issuers a verifier accepts. See Issuer trust anchors.

x5c : The JOSE header carrying an X.509 certificate chain, leaf first. Both services emit it on everything they sign, and it is where a verifier finds the issuer's certificate.

x509_hash : The verifier's OID4VP client_id, formed as x509_hash: followed by a base64url SHA-256 hash of its own leaf certificate. Because the identifier is a hash of the certificate, a verifier cannot claim an identity it holds no key for. See Trust model.

Status list : A signed bit array published by an issuer, one bit per issued credential. Each credential carries its index (idx); setting the bit revokes it. See Revocation.

Sessions and integration

Session : One issuance or one verification, from the moment your application starts it to the moment it completes. Identified by a session_id, which appears in the response that starts it, in the status endpoint, and in the result pushed to you. Issuance sessions report STARTED / SUCCEEDED / FAILED; verification sessions report VERIFICATION_STARTED / VERIFICATION_SUCCEEDED / VERIFICATION_FAILED. Both carry an error_message on failure.

Session callback : The POST a service makes to your application when a session completes, configured as sessionCallback on both services. Formerly claims on the verifier, and still accepted under that name. See Receive the issued credential and Receive verified data.

Pre-authorized code : A short-lived, single-use token proving the holder was authenticated before a credential is issued, exchanged at a token endpoint for an access token. The grant type is urn:ietf:params:oauth:grant-type:pre-authorized_code. Either your own OAuth 2.0 server issues it, or the issuance service generates one itself. See OAuth 2.0 integration.

Request URI : The address a wallet fetches a verifier's signed authorization request from, returned when you start a verification session. The issuance equivalent is the credential offer URI.

API key : A bearer token authenticating your application to the administrative endpoints of either service. Configured under integrations.authentication, where the JSON key is the token. See API keys.

A note on "DID"

"DID" is used in two distinct senses, and it is worth keeping them apart:

  • Decentralized Identity — the product and the general approach, which is how this documentation uses it.
  • Decentralized Identifier — the W3C specification for identifiers such as did:jwk:…, one of which appears in every credential's sub claim.

Where the distinction matters, this documentation writes the second sense as "decentralized identifier".