Skip to content

Revocation

A credential can be invalidated after it has been issued. Because a verifier does not contact you at verification time, revocation cannot work by deleting something on your side — instead every credential carries a pointer to a status list you publish, and a verifier checks it.

This follows the IETF Token Status List specification.

Revocation is an index, not a lookup

Revocation does not work by changing something a verifier queries about a specific credential. Each credential carries its own index into a status list the issuance service publishes, and revoking sets the bit at that index.

How it works

Each credential you issue is assigned an index in your status list. The credential's status claim records both the index and where the list lives:

"status": {
  "status_list": {
    "idx": 3,
    "uri": "https://issuer.example.org/credential-status/status-list"
  }
}

The status list is a bit array: one bit per issued credential, at the credential's index. Revoking a credential sets its bit. A verifier fetches the list, reads the bit at idx, and rejects the credential if it is set.

The list is served as a signed JWT with content type application/statuslist+jwt, signed with the same key and certificate the issuance service uses for credentials — so a verifier can confirm the list genuinely came from you. It is compressed, so a list covering many credentials stays small.

Revoke a credential

POST to /credential-status/revoke/{index}, where {index} is the credential's idx:

curl -X POST 'https://issuer.example.org/credential-status/revoke/3' \
  -H 'Authorization: Bearer <your API key>'

A successful call returns 204 No Content. Revoking an index that has never been issued returns 404.

Response Meaning
204 Revoked.
401 Missing or unrecognized API key.
404 No credential exists at that index.

Record the index at issuance time

Revocation addresses a credential by index, and there is no lookup from a session_id or a holder to an index. Nothing else in the system remembers which index belongs to which person.

The index is in the credential itself, which you receive if you have configured the callback. Store the idx alongside your own record of who the credential was issued to, at the moment you issue it. Without it you cannot revoke a specific credential later.

Revocation is one-way. There is no un-revoke endpoint. To restore a holder, issue a new credential.

Publishing the list

The status list is served from your issuance service, unauthenticated, because verifiers need to reach it:

curl 'https://issuer.example.org/credential-status/status-list?tenant=0' \
  -H 'Accept: application/statuslist+jwt'

The uri embedded in your credentials is derived from baseUrl, so the same rule applies as everywhere else: it must be an address a verifier can reach. A baseUrl of localhost produces credentials nobody else can check the status of. See Going to production.

Caching and statusListTtl

The status list token carries an expiry, controlled by statusListTtl in the service configuration — seconds, defaulting to 600. It sets how long a verifier may treat a fetched list as current.

This is the delay between revoking a credential and verifiers acting on it. Shorten it if you need revocation to take effect quickly; lengthen it to reduce how often verifiers fetch the list. See the configuration reference.

On the verifier side

A verifier following the status list rejects revoked credentials without you being involved.

Note that the verification service checks the status list for mdoc credentials, where the reference is carried in the credential's signed metadata. Whether any given third-party verifier checks your list is up to that verifier — publishing the list is what you control.

What's Next