# 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**

```bash
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**

```bash
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:

```json
"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}`).