A verifiable credential or mobile document that cannot be revoked is a liability, but a revocation check that phones home to the issuer for every presentation lets the issuer track where its holders go. The IETF Token Status List solves this by publishing the status of many tokens as one compressed, signed bit array that relying parties download and cache, so the issuer never learns which credential is being checked. It is the revocation mechanism used across SD-JWT VC, mdoc and wallet attestation ecosystems, including those built for the EU Digital Identity Wallet. This guide explains the data structures and exact draft status, the validation algorithm, caching and freshness, privacy controls such as herd size and random indices, how it compares with CRLs, OCSP and the W3C Bitstring Status List, and how to operate one as an issuer or consume one as a verifier. For credential fundamentals see the Verifiable Credentials Guide.
Key takeaways
- Nearly an RFC, not yet one. draft-ietf-oauth-status-list-21 (21 June 2026) has passed the IESG and sits in the RFC Editor queue as a Proposed Standard, with no RFC number assigned when checked on 27 October 2026. Technical content should now be stable, but the EKU object identifier is still marked TBD.
- One bit array, many tokens. Each credential carries a
status_listreference with an index (idx) and a URI; the list uses 1, 2, 4 or 8 bits per token, compressed with DEFLATE and ZLIB, inside a signedstatuslist+jwtor CWT. - Herd privacy is the point. Because the relying party downloads the whole list, the issuer cannot tell which token is being checked; that only holds if lists are large and indices are not unique per holder.
- Validate the token first, status second. The draft says token processing rules take precedence: an expired token with a VALID status is still expired, and an out-of-bounds index must be rejected.
- Freshness is a policy decision.
expandttlin the Status List Token, not HTTP cache headers, decide how long a relying party may rely on a downloaded list; revocation is only as fast as that window.
Roles and artefacts
| Role or artefact | What it is | Notes |
|---|---|---|
| Issuer | Issues the Referenced Token (credential, mdoc, attestation, access token) | Allocates the index at issuance |
| Status Issuer | Signs Status List Tokens | The Issuer or an entity it authorises |
| Status Provider | Serves Status List Tokens at an HTTP endpoint | Can be a CDN; integrity comes from the signature, not the host |
| Relying Party | Fetches the list and checks the index | Equivalent to the verifier in SD-JWT terms |
| Referenced Token | Any JOSE or COSE token: JWT, SD-JWT, SD-JWT VC, CWT, SD-CWT, ISO mdoc | Carries status.status_list.idx and uri |
| Status List | JSON object with bits and base64url lst (or CBOR equivalent) | Optional aggregation_uri |
| Status List Token | JWT with typ statuslist+jwt, or a CWT | Claims sub (its own URI), iat, exp, ttl, status_list |
The sub of the Status List Token must equal the uri in the credential, which prevents an attacker substituting a different, validly signed list. The list is served by HTTP GET with media type application/statuslist+jwt or application/statuslist+cwt, should support CORS for browser clients, and should use content encoding such as gzip for JWTs.
Status values and encoding
| Value | Name | Meaning |
|---|---|---|
| 0x00 | VALID | Valid, correct or legal |
| 0x01 | INVALID | Revoked, annulled or cancelled |
| 0x02 | SUSPENDED | Temporarily invalid |
| 0x03 and 0x0C to 0x0F | Application specific | Permanently reserved for application use |
- Bit width:
bitsof 1 allows two states (valid or invalid); 2 bits allows four, which is enough for suspension. Use the smallest width you need. - Bit order: bits are packed from least significant to most significant within each byte, while bytes are indexed in order. The draft warns that incorrect implementations miscalculate the bit and byte index, and asks implementers to verify against its test vectors.
- Default value: initialise the array with the most common value (usually 0x00) so issuance does not require a list update, compression stays effective and unused indices cannot be told apart from issued ones.
Size in practice
The draft's own size tables show why bit arrays scale where CRLs struggle. For one million entries with 1% revoked, the compressed status list is about 13.7 KB, against about 157.7 KB for a compressed array of 128-bit identifiers approximating a CRL; for 100 million entries at 1% the figures are about 1.3 MB against 15.3 MB. Sizes peak at a 50% revocation rate and are smallest near 0% or 100%. These are payload sizes only, without signatures or metadata.
Validation algorithm for relying parties
- Validate the credential: signature, issuer, expected claims and expiry, as its own format requires. Reject on failure; status checks never rescue an invalid token.
- Find the reference: require
statusandstatus_listwith a non-negative integeridxand a validuri. - Resolve the list: GET the URI (or use a cached copy still within
ttlandexp), following redirects safely. - Validate the Status List Token: signature with a trusted key,
typ, required claims,subequal to the credential'suri, not expired, andiatfresh enough for local policy. - Decompress and index: inflate with DEFLATE and ZLIB, read
bitsat positionidx; ifidxis out of bounds, reject. - Decide: accept only VALID unless your policy defines otherwise; treat any processing failure as "no statement possible" and, per the draft, the token should then be rejected.
- Trust in the list signer: the draft leaves key resolution to ecosystems but suggests the same key or
x5cas the credential when issuer and Status Issuer are the same, the same web-based key resolution, or for separate entities certificates from the same CA with a dedicated Extended Key Usage (id-kp-oauthStatusSigning, OID still TBD). - Delete what you do not need: the draft recommends that relying parties delete the
statusclaim after validation and discard old Status List Tokens, becauseuriplusidxuniquely identifies a holder.
Freshness, caching and availability
- exp: an absolute time after which the list must not be relied on.
- ttl: seconds after fetching when a new version may be available; the relying party should refetch once fetch time plus
ttlhas passed. The draft recommends issuers set both. - Precedence: when HTTP caching headers are present, relying parties must prioritise
expandttlin the token. - Abuse bounds: clients should apply lower and upper bounds to
expandttl, since a malicious or faulty Status Issuer could otherwise trigger floods of requests. - Offline verification: Status List Aggregation lets an issuer publish all its list URIs (via issuer metadata or
aggregation_uri) so verifiers, such as a border or venue device, can prefetch lists and verify offline within the freshness window. - Historical lookups: an optional
timequery parameter returns the list as it was at a past time (501 if unsupported, 404 if that time is unavailable). The draft recommends not supporting it without strong reasons because of its privacy impact.
| Use case | Suggested ttl range (policy) | Rationale |
|---|---|---|
| High-value financial or age-restricted sale | Minutes | Revocation must bite quickly; online verifiers |
| Workforce or membership credentials | Hours | Balance load and revocation latency |
| Offline or intermittently connected verifiers | Up to a day, with exp as hard stop | Prefetch through aggregation |
| Wallet or key attestations | Hours | Revoke compromised app versions promptly |
These ranges are design suggestions, not values from the draft; set them from your own risk assessment and the ecosystem profile you follow.
Privacy design for issuers
- Size the herd: privacy depends on how many tokens share a list. Larger lists cost bandwidth but hide each holder better. The W3C Bitstring Status List sets a minimum of 131,072 entries for the same reason, a useful benchmark.
- Random indices: choose non-sequential, pseudo-random indices so list position does not reveal issuance order or volume.
- Decoys and multiple lists: use decoy entries and several concurrent lists to hide true issuance and revocation rates from outsiders who download lists repeatedly.
- No unique lists or URIs: the draft identifies one list per token, or unique URI components per token, as ways an issuer could defeat herd privacy; relying parties verifying many tokens can detect it by comparing list counts with token volume.
- Batch issuance: for unlinkability across relying parties, issue batches of one-time-use credentials, each with its own index, and give every re-issued credential a fresh entry. Note that revoking a whole batch at once can reveal it was a batch.
- Prevent double allocation: never reuse
uriplusidxfor different tokens; the draft says the Status Issuer must prevent unintended double allocation. - Minimal status types: statuses beyond VALID and INVALID, including SUSPENDED, leak information to observers; consider revoke and re-issue instead.
- Hide the relying party: serve lists through a CDN or separate Status Provider, and support relay mechanisms such as Oblivious HTTP (RFC 9458), so the issuer cannot see who fetches.
Choosing a revocation mechanism
| Mechanism | Status (checked 27 October 2026) | Privacy from issuer | Scale | Best fit |
|---|---|---|---|---|
| IETF Token Status List | Internet-Draft -21, RFC Editor queue | Good (herd privacy) | Millions of tokens per list | SD-JWT VC, mdoc, CWT, wallet and key attestations, access tokens |
| W3C Bitstring Status List v1.0 | W3C Recommendation, 15 May 2025 | Good (minimum list size) | Similar | W3C VC Data Model credentials |
| X.509 CRL | RFC 5280 | Good, but lists grow with revocations | Poor at very large scale | Certificates |
| OCSP | RFC 6960 | Poor: reveals what is checked unless stapled | Good | TLS and enterprise PKI |
| Token introspection (RFC 7662) | RFC | None: per-token call to issuer | Per request load | Opaque OAuth access tokens within one domain |
| Short-lived credentials, no revocation | Design choice | Best | High re-issuance load | Credentials refreshable daily or more often |
Many ecosystems combine short validity with status lists for longer-lived credentials. For certificates see the Certificate Revocation Guide; for OAuth tokens see the OAuth Token Introspection and Revocation Guide.
Implementation roadmap
- Decide the policy: which events revoke or suspend (holder request, fraud, death, device compromise, key loss), who may trigger them, and the maximum acceptable revocation latency.
- Design lists: bit width, list size, number of concurrent lists, alignment with credential expiry (so old lists can be retired once all their tokens expire), random index allocation and default value.
- Set up signing: choose whether the credential issuer signs lists or a separate Status Issuer does, and how verifiers obtain and trust that key; protect it like the credential signing key.
- Publish: serve lists from a highly available Status Provider or CDN, with CORS and compression, and stable URIs.
- Test decoding: run the draft's 1, 2, 4 and 8-bit test vectors in both issuer and verifier code before go-live.
- Pilot with verifiers: confirm they enforce
submatching, bounds checking,expandttl, and fail closed. - Operate: monitor publication latency from revocation decision to new list, and keep the previous list available until its
expin case a bad publication must be rolled back (re-sign the corrected list; never edit a signed list in place).
Detection and measurement
- Revocation latency: time from revocation decision to a published list, and to the end of the longest relying party cache window.
- Publication health: signature validity, list size, expiry headroom and endpoint availability, alerting before
explapses. - Abuse indicators: unusual fetch volume per list (scraping to infer rates), requests for historical times, or a revoked credential's presentation attempts at relying parties.
- Verifier compliance: sample relying parties for correct fail-closed behaviour.
| Metric | Target |
|---|---|
| Decision-to-publication time for revocations | Within policy, for example under 15 minutes |
| Status List Token availability | Same tier as credential issuance, for example 99.9% or better |
| Lists below minimum herd size | Zero |
| Verifiers passing fail-closed and bounds tests | 100% of onboarded relying parties |
| Double-allocated indices detected | Zero |
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | IA-5 Authenticator Management; IA-5(2) Public Key-based Authentication | Revocation status checking for credentials and keys |
| NIST SP 800-53 Rev. 5 | SC-17 Public Key Infrastructure Certificates; IA-4 Identifier Management | Status signing keys, EKU, index and identifier allocation |
| NIST SP 800-53 Rev. 5 | SC-5 Denial-of-service Protection; AU-10 Non-repudiation | Bounds on refresh, signed status assertions |
| NIST CSF 2.0 | PR.AA-01 | Credentials are managed through their life cycle, including revocation |
| ISO/IEC 27001:2022 Annex A | 5.16 Identity management; 5.17 Authentication information | Life cycle of issued identities and their invalidation |
Where identity fits: status lists beyond citizen credentials
Status lists are not only for driving licences and diplomas. The draft's first example use case is the status of OAuth access tokens: instead of each resource server calling token introspection for every request, it can download one list covering many tokens and cache it, which reduces load on the authorisation server. The same mechanism is referenced by OpenID4VCI for the optional status claim in both Wallet Attestations and key attestations, so a wallet provider can revoke attestations for an app version found to be vulnerable, or for keys in a storage component that failed certification.
- Machine credentials: long-lived JWT or CWT credentials issued to devices, workloads or agents can carry a status reference, giving fleet-wide revocation without a CRL distribution problem. See the Non-Human Identity (NHI) Guide.
- Agent delegation tokens: where an AI agent holds a credential delegated by a user, a status list lets the user or administrator withdraw it at every verifier at once.
- Ownership: whoever can set a bit to INVALID can switch off a credential everywhere. Treat the revocation interface and the Status Issuer key as privileged, with approvals and logging.
Common failure patterns
- Checking status before validating the token: accepting an expired or badly signed credential because the list says VALID.
- Not checking
sub: a validly signed list for a different URI is accepted. - Off-by-one bit order: reading bits most significant first silently checks the wrong token.
- Fail open: treating an unreachable list, decompression error or out-of-range index as valid.
- Tiny lists: a list per customer organisation or per day of issuance with only a few hundred entries undermines herd privacy.
- Caching beyond policy: relying on HTTP cache headers or a CDN default instead of the token's
expandttl.
Practitioner checklist
- Record the draft version and status you implement, and re-check before release.
- Define revocation and suspension policy, triggers, authority and latency targets.
- Allocate random, never reused indices in large lists with a default of VALID.
- Set both
expandttl, and document verifier bounds. - Run the draft's test vectors in issuer and verifier code.
- Make verifiers validate the token first, match
subtouri, check bounds and fail closed. - Serve lists via a highly available provider with CORS and compression; disable historical lookups unless required.
- Monitor publication latency, list expiry and fetch anomalies.
Standards and references
- IETF: Token Status List (Internet-Draft)
- IETF OAuth Working Group: Token Status List editor's copy
- W3C: Bitstring Status List v1.0
- OpenID Foundation: OpenID for Verifiable Credential Issuance 1.0
- OpenID Foundation: OpenID4VC High Assurance Interoperability Profile 1.0
- NIST: SP 800-53 Rev. 5
Related NHI Mgmt Group resources: Verifiable Credentials Guide · SD-JWT and SD-JWT VC Guide · Digital Identity Wallets Guide · EUDI Wallet Architecture and Reference Framework Guide · Certificate Revocation Guide