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

Status lists and revocation

When a credential can be revoked (or suspended), holders and verifiers need a public, cacheable way to learn the current status without calling your private APIs. A status list is a large array of compact status values, packaged as a signed token that verifiers fetch by URI. Each issued credential carries a pointer: which list, and which index in that list.

Operators create and size lists before issuance. The issuer allocates indexes when credentials are issued. Later, an operator or automation updates the value at an index (for example revoked). The next published token reflects that change.

Whether any list already exists depends on product onboarding and sample data. Empty is normal for a clean production tenant.

Audience: tenant admin (or platform operator in a tenant context).

Prerequisites: Onboard a tenant. Issuance of revocable credentials also needs a working issuer, a signing identity for the list (see Keys and DID), and designs that put a status claim on the VC.

Reference: Status lists
APIs: Status list management, Status list hosting.

Guide variables useful for live Run: statusListId, statusListIndex, signing key alias, public list URI.

How it fits issuance​

  1. Create a status list with enough capacity for expected credentials and a public URI verifiers can reach.
  2. Configure issuance (design / issuer settings) so each revocable credential gets a status claim pointing at that URI and an allocated index.
  3. When you must revoke or suspend, update that index (by index or by business entry key).
  4. Verifiers refresh the hosted token and read the bit(s) at the index.

Do not reuse indexes across unrelated credentials. Capacity is finite: plan length for growth, not only the first pilot.

Select the status representation deliberately​

StatusList2021/W3C Bitstring Status List and the IETF Token Status List are different wire representations. The list's specification, purposes, bit width, proof format, hosting mode, and public URI must agree with the credential format and verifier ecosystem.

ChoiceUse whenVerify in the walkthrough
W3C Bitstring / StatusList2021The credential profile and verifier expect a VC-oriented bitstring status listList type, bitstring/VC-JWT publication, status reference, and verifier refresh
IETF Token Status ListThe wallet/verifier ecosystem expects a compact status tokenToken status-list type, JWT or CWT proof, public fetch, cache TTL, and status transition

JWT, CWT, and VC-JWT describe the published proof/container, not three interchangeable list semantics. Use the exact content type and proof format advertised by the configured list. Revoke, suspend, and reactivate update the list entry; they do not rewrite the credential signature, so verification must fetch or refresh the current published token before deciding.

For complete issuer-to-verifier request chains, including SD-JWT VC, CWT/mDoc, and W3C VCDM 1.1/2.0 StatusList2021 examples, see Credential status profile walkthroughs.

CWT status list for an mdoc​

For an ISO mdoc status reference, create a one-bit Token Status List with the cwt proof format and the status_list mdoc profile:

POST /api/statuslist/v1/statuslists
Content-Type: application/json

{
  "correlationId": "mdoc-revocation",
  "spec": "token_status_list",
  "proofFormat": "cwt",
  "mdocProfile": "status_list",
  "issuer": "https://issuer.example.com",
  "signingKeyMode": "x5c",
  "kmsResourceHandle": "krh_example_mdoc_status",
  "kmsKeyAlias": "mdoc-status-signing",
  "statusListUri": "https://issuer.example.com/public/statuslists/mdoc-revocation",
  "purposes": ["revocation"],
  "length": 256,
  "bitsPerStatus": 1
}

The public URL returns raw application/statuslist+cwt bytes containing a COSE_Sign1 CWT. It is not a compact JWT and is not base64 text at the HTTP boundary. The mdoc MSO points to that stable URI and an allocated index, for example { "status_list": { "idx": 42, "uri": "https://issuer.example.com/public/statuslists/mdoc-revocation" } }. The CWT protected header carries the media type, algorithm, and the required certificate chain; its inner one-bit payload uses bits and lst.

The repository's focused CWT tests cover signing, hosting, resolution, revocation, identifier-list uniqueness, protected-type rejection, algorithm rejection, and fail-closed unavailable publication. See mDoc VICAL and CWT status for the complete use case and mDoc second-edition use cases for the DeviceRequest/DeviceResponse/MSO examples.

List status lists​

The inventory shows list slug (correlation id), specification, purposes (revocation, suspension, and so on), proof format, hosting mode, remaining capacity, and last update. Filter by spec or purpose when many lists exist. Open a row for overview, entry updates, and the signed token.

Navigation: Resources > Status Lists > Lists
Deep link: #resource=statuslists&rarea=lists

An empty list only means none were created yet. If the product reports that an OID4VCI issuer is not configured, fix issuer setup before creating lists.

Status lists inventory

Validation example (sanitized tenant):

Status-list inventory example

Create a status list​

Create before you issue revocable credentials that need a place to allocate indexes. Defaults below match a common IETF Token Status List setup; adjust for your threat model and wallet ecosystem.

DecisionWhy it matters
List slug (correlation id)Stable business id. Often appears in the public path. Hard to rename once credentials point at the URI.
Registered issuerDID (or product-equivalent) that signs or is bound as the list issuer in metadata. Must match what verifiers expect.
SpecificationToken Status List vs bitstring list (and related). Pick what your wallets and verifiers implement.
PurposesRevocation alone is 1-bit friendly. Suspension typically needs at least 2 bits per status so values can distinguish valid / revoked / suspended.
Proof formatJWT, CWT, or VC-JWT for the published token. Must match verifier support.
LengthNumber of indexes. Under-sizing forces a second list mid-lifecycle. Over-sizing wastes storage and publish cost.
Bits per status1 for simple revoke/valid; 2+ for suspension or multi-value status.
Hosting modeHosted: platform publishes at a derived public URI. Export: you host the token yourself and supply the external URI.
TTLHow long caches may treat a fetched token as fresh. Too long delays visibility of revocations; too short increases load.

Indexes for issued credentials are allocated by the issuer at issue time (often non-sequential) so list position does not leak issuance order.

The create capture may use template placeholders ({{tenantStatusListApiBaseUrl}}, ...). With a connected environment, substitute via guide variables or edit the request on the Request tab before Run.

New status list opens the create dialog. Fill slug, issuer, purposes, capacity, and hosting, then create. The console opens the new list detail when creation succeeds.

New status list dialog

Inspect a list (Overview)​

Overview is the operational identity of the list: internal id, slug, spec, purposes, proof format, hosting, issuer DID, capacity, content type, and public URI. Copy the public URI into credential status claims and into any design or issuer config that must reference this list.

Capacity shows how many slots remain. When remaining capacity is low, plan a new list and cut over issuance before you run out.

Open a list row. Overview is the default tab.

Status list Overview

Entries: lookup, revoke, reactivate, suspend​

The Entries tab is where operators change a credential's status after issuance.

  1. Locate the entry by status-list index (from the credential status claim) or by entry business key when your issuer stored one.
  2. Lookup to see the current value.
  3. Apply an action: revoke, reactivate (clear revocation when the product allows), or suspend when bits-per-status supports it.

For a typical 1-bit revocation list: value 1 means revoked, 0 means valid (or unused). Unallocated indexes are intentionally hard to distinguish from valid zeros on the public read path, which limits probing.

Revocation is a security action. Prefer automation with audit over ad-hoc console use in production, but the console is valid for break-glass and lab work.

Status list Entries tab

Signed token and public hosting​

Verifiers do not call the management API. They fetch the signed status list token from the public URI (no bearer). That surface must stay available independently of the Admin Console, and it should be cache-friendly within the TTL you chose.

Signed token in the console shows the current published token and content type so operators can debug publish failures without leaving the product. Prefer the public URL for real verifier checks.

Public URI is on Overview. Token payload is under Signed token.

Status list Signed token tab

After status lists​

  1. Point credential designs / issuer issuance config at the list slug or public URI as your product expects
  2. Issue credentials so indexes are allocated
  3. Verify credentials including status checks
  4. Automate revoke/reactivate against the management API for production operations

Next​