Skip to main content
Version: v0.25.0 (Latest)

Credentials, status, and trust

This guide is the starting point for an issuance or verification implementation. It explains which choices belong together, shows the matching Admin Console screen, and places the captured request, captured response, and live Scalar/OpenAPI operation beside the explanation.

Every REST + captured result panel uses four inner tabs:

  • Overview identifies the endpoint and captured status.
  • Request shows the sanitized request that was actually captured.
  • Response shows the corresponding captured response.
  • API reference embeds the same operation from the current OpenAPI contract in Scalar, including schemas and examples.

The captures prove only the displayed boundary. They do not prove a complete wallet flow or a different deployment. Use customer-neutral values and never place secrets, private keys, access tokens, or customer identifiers in a guide or Postman environment.

Select one coherent profile​

Credential format and status format are a paired protocol choice. Do not issue one format and attach a status reference shaped for another.

Credential profileOID4VCI formatStatus mechanismHosted media typePrimary trust input
SD-JWT VCdc+sd-jwtIETF Token Status List signed as JWTapplication/statuslist+jwtDID/JWK or X.509 evidence admitted by a trust domain
ISO mdocmso_mdocIETF Token Status List signed as CWTapplication/statuslist+cwtDSC chain to an admitted IACA; VICAL may distribute mdoc trust anchors
W3C VCDM 1.1 in JWTjwt_vc_jsonStatusList2021 bitstring credential signed as JWTapplication/vc+jwtDID/JWK or X.509 evidence admitted by a trust domain
W3C VCDM 2.0 in JWTjwt_vc_json-ldStatusList2021 bitstring credential signed as JWTapplication/vc+jwtDID/JWK or X.509 evidence admitted by a trust domain

jwt_vc_json-ld means a JWT-encoded VCDM 2.0 JSON-LD credential. It is not the same wire contract as VCDM 1.1 jwt_vc_json. The credential @context, type binding, claim paths, and issuer metadata must match the selected row.

What each layer decides​

LayerQuestion answeredCommon mistake
Credential designWhat is issued, in which format, with which claims and OID4VCI configuration id?Treating an mdoc namespace path as a JSON claim path
KMS key/certificateWhich provider-native object performs the cryptographic operation?Assuming a KMS resource id itself establishes issuer trust
Status listIs the credential's indexed status currently valid?Using JWT Token Status, CWT Token Status, and StatusList2021 interchangeably
Trust domainWhich issuer or signer evidence is admitted for this consumer?Assuming a valid signature is automatically trusted
DCQLWhich credential formats and claims must the holder present?Querying the wrong format identifier or claim path
Protocol sessionDid issuance or presentation complete?Treating session creation as proof that a wallet stored or presented a credential

1. Define the credential design​

Create the semantic model and claim paths first. Then bind that model to the wire format and a stable credentialConfigurationId. Wallets use this identifier when selecting a configuration from issuer metadata.

Navigation: Resources > Credential Designs > Credential designs

Deep link: #resource=credentialDesigns&rarea=credential-designs

Credential designs library in the Admin Console

Open a design and inspect Overview for its format binding and Claims for its format-specific paths. A saved design is configuration; issuance still requires an issuer binding, signing selection, and protocol session.

Format-specific design rules​

  • SD-JWT VC: use dc+sd-jwt, a stable vct, and explicit disclosure policy. A disclosed claim is released by the holder; it is not encrypted merely because undisclosed claims remain hidden.
  • mdoc: use mso_mdoc, the correct docType, and ISO namespace/element identifiers. The DSC certificate chain and device-authentication behavior are part of verification.
  • VCDM 1.1 JWT: use jwt_vc_json, the VCDM 1.1 context, and the intended type values.
  • VCDM 2.0 JWT: use jwt_vc_json-ld, the VCDM 2.0 context, and VCDM 2.0 claim semantics. Do not silently downgrade it to a 1.1 JWT VC.

2. Select keys and certificates​

The credential design says what will be signed; the signing selection says which key performs the operation. For an external provider, the runtime must retain the provider-native key alias as well as the EDK resource handle.

Navigation: Resources > KMS > Providers, Keys, or Certificates

KMS providers in the Admin Console

Use Keys to generate or register an existing provider-native key. Use Certificates to register public certificate material and its relationship to the key. Registration must never require exporting an external private key.

For mdoc, the KMS public key, DSC certificate, credential x5chain, and admitted IACA must describe the same chain. Azure Key Vault can protect the signing operation; it cannot decide which IACA is trusted.

3. Create the matching status list​

Create the list before issuance so the credential can carry a stable URI and index. The status-management API controls list lifecycle and entries; the public hosting API returns the signed artifact consumed by verifiers.

Navigation: Resources > Status Lists > Lists

Deep link: #resource=statuslists&rarea=lists

Status-list inventory in the Admin Console

The detail page separates configuration, entries, and the hosted token. Verify the proof format and public media type before allocating production entries.

The credential must reference the same list and entry using its own format-specific structure:

  • SD-JWT uses its token-status claim and a JWT status-list endpoint.
  • mdoc carries status metadata in the issuer-signed structure and points to a CWT status-list endpoint.
  • VCDM 1.1 and 2.0 use credentialStatus and a StatusList2021/bitstring status-list credential.

See Credential status profile walkthroughs for complete request bodies, media types, and valid-to-revoked checks.

4. Establish verifier trust​

A cryptographically valid credential can still be untrusted. A trust domain records the anchors, admission classes, sources, and consumer attachment used to decide whether an issuer or signer is accepted.

Navigation: Resources > Trust domains > Domains

Verifier attachment: Open Protocols > Verifier > Settings > Trust domains

Trust-domain inventory in the Admin Console

Create the domain, add anchors and their admissions, activate it, and attach it to the intended tenant, verifier, query, or template consumer. A narrower attachment replaces the broader selection; it does not merge silently with it.

mdoc, IACA/DSC, and VICAL​

The mdoc signer uses a Document Signer Certificate (DSC), which chains to an Issuing Authority Certificate Authority (IACA). A VICAL is a signed CBOR/COSE artifact for distributing mdoc certificate-authority information. It is trust material; it is not credential status.

The configured VICAL signer anchors need the appropriate VICAL-signer admission, while document issuers need the credential-issuer admission. The management contract below validates and stores VICAL configuration on a trust anchor.

Loading example...

Configuration alone is not proof that a running verifier fetched, parsed, cached, cryptographically verified, and enforced a remote VICAL. When claiming runtime VICAL support, capture each of those boundaries and prove fail-closed behavior for an untrusted signer, expiry, malformed content, and unavailability. Read mDoc VICAL and CWT status for the complete separation.

5. Issue the selected format through OID4VCI​

An offer selects an advertised credential configuration. The wallet resolves the offer, obtains an access token, and requests that exact format. The issued credential must contain the status reference allocated earlier.

Navigation: Open Protocols > Credential Issuer > Credentials, then Test

Credential issuer configurations in the Admin Console

Use the testing surface to inspect the resolved configuration and status selection before execution. A successful server-side session does not by itself prove wallet storage.

Credential issuer testing surface in the Admin Console

6. Query, present, and verify​

DCQL describes what the verifier requests; trust and status decide whether the returned credential is acceptable. Keep those decisions observable and separate.

Navigation: Open Protocols > Verifier > DCQL & Bindings, then Test

DCQL query bindings in the Admin Console

Bind a pinned query version to the intended verifier. Then use Test with a real wallet when claiming holder presentation, device binding, or interoperability.

Verifier testing surface in the Admin Console

7. Prove fail-closed behavior​

First prove the valid path. Then revoke the same entry, refresh the verifier's view, and prove rejection of the same credential. Also test:

  • status publication unavailable, expired, malformed, signed by the wrong issuer, or served with the wrong media type;
  • trust domain inactive, unattached, empty, or attached at the wrong consumer level;
  • certificate chain expired, unrelated to the signing key, or anchored outside the admitted IACA set;
  • SD-JWT disclosures or holder binding that do not satisfy policy;
  • mdoc issuer authentication or device authentication failure; and
  • DCQL returning no matching credential because the format or claim path is wrong.

Run the profiles in Developer Console​

Developer Console explains how its policy-filtered OpenAPI catalog, Scalar operations, and generated Postman collection relate to these guides. The dedicated credential/status profile collection contains 19 customer-neutral requests grouped into the four rows of the selection matrix; Azure KMS, BYOK, and BYOC mutations are present but disabled by default.

Do not call the lifecycle complete until the same configured lane proves issuance, wallet receipt, presentation, signature and holder/device binding, trust admission, current status, and fail-closed rejection. A screenshot, rendered guide, successful create call, or static contract test proves only its own boundary.