Skip to main content

​
Overview

Revocation flips a single bit in your organisation’s Status List 2021 bitstring. Verifiers — including the Beltic verify endpoint and any offline verifier — see the revocation on their next bitstring fetch. There’s no per-credential round-trip; revocation propagation is bounded by the bitstring’s cache TTL.

​
Prerequisites

  • A Beltic API key with credentials:revoke permission
  • The credential_id of the credential you want to revoke

​
Step 1: Send the Revoke Request

The reason field is optional but recommended. Use it for audit context — common values are key_rotation, compromised, policy_change, user_request, error.

​
Step 2: Inspect the Response

The credential’s status is now revoked, and the bit at status_list_index in your org’s bitstring has been flipped. The signed JWT itself is still cryptographically valid — revocation is a separate signal that lives outside the signature.

​
How Verifiers See the Change

Revocation propagates through the status list, not through the credential itself:
1

Beltic flips the bit

POST /revoke writes the updated bitstring to S3 at the public status-list URL (/.well-known/status-lists/v1).
2

Verifiers fetch the bitstring

Every verify call fetches (or uses a cached copy of) the org’s status list. Cache-Control on the response is 60 seconds by default.
3

The bit is checked at the credential's slot

During step 6 of the verify pipeline, the verifier reads bit status_list_index from the bitstring. If it’s set, the credential is treated as revoked.
Worst-case propagation delay: 60 seconds (the cache TTL). After that, every verifier sees the revocation.

​
Revocation Is Permanent

Revoked credentials cannot be un-revoked. The bit stays flipped for the lifetime of the credential, and the slot is not reused — Status List 2021’s protocol guarantees that a bit, once set, stays set. If you need to issue a fresh credential for the same subject, call POST /v1/credentials again with the same subject and claims. The new credential gets its own credential ID and its own status-list slot.

​
Suspension vs Revocation

Status List 2021 supports two distinct lifecycle states beyond active and expired: V1 of the Beltic API exposes only revoked via the public revoke endpoint. Suspension is reserved for internal administrative use (e.g. a fraud hold) and surfaces on verify as reason: "revoked" with status: "suspended" in the response so callers can distinguish.

​
Auditing Revocations

Every revoke call writes an immutable audit event with the credential.revoked action. Query it via:
Each audit event captures the credential ID, the actor (API key ID), the revocation reason, and a hash-chained prev_hash + row_hash pair for tamper detection. See the audit-events endpoint reference for the full shape.

​
Error Codes

​
Next Steps

Issue a Replacement

Mint a new credential for the same subject.

Verify a Credential

Confirm a credential is or isn’t revoked.