Credential Registry

A signature proves a credential is authentic, and the Trust Network proves its issuer is trusted — but neither tells you whether the credential is still valid right now. Credentials get revoked, suspended, and expire over their lifetime. The Network Credential Registry is how that lifecycle state is recorded and checked at verification time — without the verifier ever contacting the issuer.

Together with the Trust Network, the registry is one of the two platform components that turn a raw signed credential into a trustworthy, current assertion:

• Trust Network — should I trust who issued this?
• Credential Registry — is this credential still valid, or has it been revoked/suspended?

What it is

The Network Credential Registry tracks the lifecycle status of every credential issued through iDen2. It implements the W3C Bitstring Status List 1.0 standard, which makes status checks privacy-preserving:

• Each credential is assigned a single bit position in a shared, published status list.
• The status list is a compressed bitstring served at a public URL.
• A verifier fetches the list, decompresses it, and checks one bit — 0 = valid, 1 = revoked (or suspended).

Because the verifier reads a large shared list rather than asking about one specific credential, the issuer is never told when or where a credential is verified, and the verifier never reveals which credential it is checking. This "herd privacy" is the reason status lists are used instead of a per-credential lookup API.

How it participates in the flows

At issuance

When Credential Factory issues a credential, the platform automatically registers it in the registry and embeds a status reference (a W3C BitstringStatusListEntry) inside the issued SD-JWT. As an issuer you do not call the registry to issue — you just create the offer; the status entry is added for you.

After issuance you can poll GET /api/v1/iaas/credential-offers/{offerId}; once claimed, the response includes a credentialStatus block (statusListId, statusListIndex, statusListCredential) so you can correlate the credential to its registry entry.

Changing status (revoke)

An issuer with the right permission changes a credential's status through the Issuer API — for example to revoke a compromised credential:

curl -X POST "https://iaas.stg.iden2.app/api/v1/issuer/credentials/{credentialId}/revoke" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "revoke", "reason": "holder_request"}'

The change flips the credential's bit in the published status list, so the next verification of that credential will see it as revoked. Credential Factory supports revoke only today: credentials are registered on a revocation status list, so suspend returns 501. See the Network Credential Registry guide for the full status API.

At verification

When a holder presents a credential, Verification Gateway resolves the embedded status reference, checks the bit, and surfaces the outcome to you in the session result:

• verificationResult.revocationStatus — not_revoked, revoked, or unknown.
• A revocation entry in verificationResult.checks[] with mechanism: "BitstringStatusList".

A revoked credential fails the session with failureReason: "revoked_credential". Always confirm revocationStatus !== "revoked" before granting access — even when status === "completed". A status of unknown means the registry could not be consulted; treat it as not-verified for high-stakes flows. See Verification Integration.

Lifecycle states

Status	Meaning
issued	Credential recorded at issuance
active	Valid and presentable
suspended	Temporarily blocked (reversible)
revoked	Permanently invalidated
expired	Past the credential's expiry
archived	Retained for audit; not presentable

Status changes carry a reason (e.g. key_compromise, holder_request, fraud_detected) for the audit trail.

Who does what

Party	Interaction with the registry
Issuer (you)	Status is registered automatically at issuance. You revoke through the Issuer API as your business rules require.
Verifier (you)	You never call the registry directly for standard flows — Verification Gateway checks status and reports revocationStatus in the session result.
Holder (wallet)	Carries the embedded status reference inside the credential and presents it; the wallet does not query the registry for standard OpenID4VP flows.

Where to go next

• Network Credential Registry guide — status API, environments, and the verification flow in detail
• Trust Networks — the other half of "should I trust this credential?"
• Verification Integration Guide — interpreting revocationStatus and verificationResult
• Credential Registry Architecture — how it is wired into Credential Factory and Verification Gateway