Skip to main content

Credential Registry Architecture

The Network Credential Registry is the platform component that records and serves credential lifecycle status (revocation, suspension, expiry). This page describes how it is wired into Credential Factory and Verification Gateway; for the conceptual introduction see Credential Registry.

It is the companion to the Trust Network: the Trust Network answers who can be trusted, the Credential Registry answers what is still valid.

Position in the platform​

The registry is consulted at two points in a credential's life, plus an out-of-band update path:

  1. At issuance — Credential Factory registers the new credential, the registry allocates a bit position in a status list, and Credential Factory embeds a BitstringStatusListEntry (the status list URL and the index) into the issued SD-JWT.
  2. At verification — Verification Gateway reads the status reference from the presented credential, fetches the published status list, and checks the bit.
  3. On status change — the issuer revokes through the Issuer API, flipping the credential's bit so subsequent verifications observe the new state. (Credential Factory supports revoke only today: credentials are registered on a revocation status list, so suspend returns 501.)

The status reference inside a credential​

Every issued vc+sd-jwt credential carries a status reference pointing at a registry-hosted, publicly readable status list:

{baseURL}/v1/status-lists/{statusListId}

This reference travels with the credential in the holder's wallet. Nothing about it identifies the individual credential to an observer — only the holder's own bit position within a shared list. Issuers can recover the reference for a claimed offer from the credentialStatus block on GET /api/v1/iaas/credential-offers/{offerId}.

Status resolution during verification​

The result surfaces to you on GET /api/v1/verifier/sessions/{sessionId}:

  • verificationResult.revocationStatus — not_revoked / revoked / unknown.
  • A checks[] entry of type revocation with mechanism: "BitstringStatusList".

Design properties worth knowing​

  • Herd privacy. A verifier downloads a shared, compressed bitstring and inspects one bit. There is no per-credential query, so the issuer is not notified of verifications and the verifier does not disclose which credential it is checking.
  • No issuer round-trip at verification. Status is read from the published list, not from the issuing system — verification keeps working even if the issuer's own backend is offline.
  • Governance-bound. What an issuer may do (e.g. whether it can revoke a given credential type) is governed by the same Trust Network policy that authorizes issuance — the two components share the network's governance model.
  • Auditable. Every status transition is recorded with a reason code for the credential's history.

Operational notes​

  • Status registration is automatic at issuance — issuers do not call the registry to issue.
  • Status changes are issuer-driven through the Issuer API (revoke); they are not something verifiers or holders perform.
  • Verifiers read, never write. For standard OpenID4VP flows you only consume revocationStatus — you do not call the registry directly.
  • Public status-list reads are unauthenticated; the credential-status management APIs require an OAuth token with credential-registry.* scopes (platform integrators only). See the Network Credential Registry guide.

Where to go next​