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 published, not answered on request

A verifier never asks you about a specific credential. Each credential carries its own index into a status list the issuance service publishes, and revoking sets the entry at that index — what a verifier reads is the list, not an answer from you.

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 an array of status entries, one per issued credential, at the credential's index. Revoking a credential sets its entry. A verifier fetches the list, reads the entry at idx, and rejects the credential if it is set.

Entries are one bit wide by default, which is enough to record revoked or not revoked. The specification allows wider entries for richer status values; the issuance service uses one bit.

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

A credential is revoked through the session that issued it. POST to /credential-status/revoke/{session_id}:

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

The issuance service remembers which status list index that session's credential took, so you never handle indices yourself. The same URI arrives ready to use as revocation_uri in the issuance callback.

A successful call returns 204 No Content.

Response Meaning
204 Revoked.
400 The session issued no credential, so there is none to revoke.
401 Missing or unrecognized API key.
404 No session exists with that id.

Record the session id at issuance time

Nothing in the system maps a holder to their credential — that link is yours to keep. Store the session_id alongside your own record of who the credential was issued to, at the moment you start the issuance. Without it you cannot revoke that person's credential later.

A session that did not complete has no credential to revoke, and answers 400.

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' \
  -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. Whether any given third-party verifier checks your list is up to that verifier — publishing the list is what you control.

What's Next