Revocations

Below is the documentation for revoking credentials and updating the on-chain status list. It includes only the steps and endpoints explicitly provided.

---

1. Revoke a Credential

Endpoint

POST /api/v1/credentials/{credentialId}/revoke
Authorization: Bearer <your-client-secret>

• {credentialId}: The UUID of the credential to revoke.

• Authentication: Use a valid client-secret bearer token.

Behavior

• Sets the revoked flag to true for that credential in the database.

• On success, returns HTTP 200 with an empty response body.

Example Request

POST /api/v1/credentials/4f8a9b3c-12d4-4e6f-8a2b-9c3d5e6f7a8b/revoke
Authorization: Bearer abcdef1234567890

---

2. Publish (Update) the Revocation List

After one or more credentials have been revoked, you must publish an updated Bitstring Status List so that verifiers can see which credentials are no longer valid.

Endpoint

POST /api/v1/blockchain/revocations/{listId}
Authorization: Bearer <your-client-secret>

• {listId}: The identifier of the status list being updated (for example, 1 for the default revocation list).

• Authentication: Use a valid client-secret bearer token.

Behavior

1. The service gathers all credentials marked as revoked = true from the database.

2. It constructs a new bitstring where each bit position corresponds to a credential’s statusListIndex, setting bits to 1 where credentials are revoked.

3. That bitstring is compressed (gzip) and published on-chain as a BitstringStatusListCredential.

4. On success, returns HTTP 200 with an empty response body.

Example Request

POST /api/v1/blockchain/revocations/1
Authorization: Bearer abcdef1234567890

---

3. How Verifiers Check Revocation Status

Each issued credential includes a credentialStatus entry in its JSON-LD, for example:

"credentialStatus": [{
  "id": "https://example.com/credentials/status/3#94567",
  "type": "BitstringStatusListEntry",
  "statusPurpose": "revocation",
  "statusListIndex": "94567",
  "statusListCredential": "https://example.com/credentials/status/3"
}]

• statusListCredential: The on-chain URI of the Bitstring Status List Credential.

• statusListIndex: The index (bit position) corresponding to this credential.

To verify a credential’s revocation status, a verifier would:

1. Read the credentialStatus object from the presented credential.

2. Retrieve the BitstringStatusListCredential from the on-chain URI given in statusListCredential.

3. Decode its encodedList (a gzipped bitstring), then examine the bit at statusListIndex:

• If the bit is 0, the credential is still valid.

• If the bit is 1, the credential has been revoked.

The exact method for fetching the on-chain JSON-LD and decoding the bitstring depends on your client implementation; no specific GET endpoint is defined here, because the status list lives externally (e.g., on a blockchain gateway or IPFS) at the URI embedded in the credential.

---

4. Extending to Other Status Purposes

To support additional purposes beyond revocation (e.g., suspension, hold):

1. Use a status_lists table keyed by (purpose, issuer_did).

2. Assign each credential a status_list_id so it knows which list it belongs to.

3. Issue or update each purpose-specific Bitstring Status List Credential with its own statusPurpose.

4. Change endpoints accordingly (for example, /api/v1/credentials/{id}/suspend or /api/v1/blockchain/status-lists/{purpose}/{id}).