# Revoke a claimed email credential

## Goal

This guide explains how to revoke a previously issued and claimed credential offer using the Issuer API. Revoking a credential ensures that it is no longer considered valid, enabling secure management of credential lifecycles. 

Prerequisite:

* Issuer API Base URL
* Issuer API Key with a role of Issuer\_Admin
* An ID of a valid claimed credential offer from Issuer API

{% hint style="info" %}
To follow along, you can refer to the [Issue an Email Credential](/tng-identity-documentation/tng-identity-issuers/issuer-api/examples/issue-an-email-credential.md) tutorial. After completing the steps to issue a credential, you will also need to claim it (e.g., using the [Identity Wallet](https://apps.apple.com/gb/app/nchain-identity/id6458102321) app) before proceeding with revocation.
{% endhint %}

## Guide

{% stepper %}
{% step %}

## Getting started

Prepare your working environment with valid values about the Identity environment you want to work on. 

For reference review the [Getting Started](/tng-identity-documentation/tng-identity-issuers/issuer-api/getting-started.md)
{% endstep %}

{% step %}

### Understanding the need for revocation

**Revocation** is a critical feature for managing the lifecycle of credentials. It ensures that invalid or compromised credentials are no longer accepted. Common scenarios requiring revocation include:

* The credential has expired or is no longer valid.
* There has been a security issue (e.g., compromised credential data).
* The subject no longer satisfies the conditions of the credential (e.g., a license has been rescinded).
* Issuers need to maintain trust by ensuring revoked credentials cannot be misused.
  {% endstep %}

{% step %}

### Prepare a valid claimed credential

Before revoking a credential, ensure you have the following:

1. **Credential offer ID.** Obtain the unique identifier for the credential offer. This ID was generated when the credential offer was created.
   * If the ID is lost, use the "[Credential Offer Pagination](broken://pages/eYPRjkL364EpxDobq1j6#private-credential-offers-1)" endpoint to retrieve a paginated list of all credential offers.

```bash
$API_KEY=INSERT_YOUR_API_KEY_HERE
$IDENTITY_ENV_HASH=426f1ce15bf3df70
$ISSUER_API_BASE_URL=https://identity.products.teranode.group/products/web/$IDENTITY_ENV_HASH/issuer
curl --location '$ISSUER_API_BASE_URL/api/v1/credential-offers' \
--header 'X-API-KEY: $API_KEY'
```

* **Claim Status**: Verify that the credential has been claimed by a holder before proceeding with revocation. Use the "[Retrieve Credential Offer](broken://pages/eYPRjkL364EpxDobq1j6#private-credential-offers-id)" endpoint to fetch the credential's details. Check the `status` field to confirm that the credential has been claimed.

```bash
curl --location 'ISSUER_API_BASE_URL/api/v1/credential-offers/<CREDENTIAL_OFFER_ID>' \
--header 'X-API-KEY: $API_KEY'
```

{% endstep %}

{% step %}

### Revoke the credential

Using the Issuer API, you can revoke a credential by calling the **Revoke** endpoint. Provide the **Credential offer ID** and, optionally, a **revocation reason** for better tracking and auditing.

The endpoint also supports **bulk actions**, allowing you to revoke multiple credentials in a single request, making it efficient for managing large-scale revocations.

```bash
curl --location --request PATCH '$ISSUER_API_BASE_URL/api/v1/credential-offers/revoke' \
--header 'X-API-KEY: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "revoke": [
        {
            "id": "<CREDENTIAL_OFFER_ID>",
            "revocationReason": "email compromised"
        }
    ]
}'
```

Replace the placeholder values in `$ISSUER_API_BASE_URL` and `$API_KEY` with the actual values for your setup. For the revocation data, provide the real UUID value for `<CREDENTIAL_OFFER_ID>` and include a **revocation reason** if applicable (the `revocationReason` field is optional).

Upon a successful response, the revoked credential data will be included in the `revocations` array. Check the `status` field in the response, which should display **revoked**. You can also verify the credential's status using the "[Retrieve Credential Offer](broken://pages/eYPRjkL364EpxDobq1j6#private-credential-offers-id)" endpoint.

{% hint style="info" %}
View [full API documentation](broken://pages/eYPRjkL364EpxDobq1j6#private-credential-offers-revoke) for endpoint used in this section
{% endhint %}
{% endstep %}
{% endstepper %}

## Conclusion

Revoking a credential offer is a vital step in maintaining the integrity of your credential system. By identifying the credential, performing the revocation securely through the API, and notifying all stakeholders, you can ensure trust and compliance in your credential management processes.

This guide equips you to handle revocations effectively, minimizing risks and preserving the credibility of your system.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.teranode.group/tng-identity-documentation/tng-identity-issuers/issuer-api/examples/revoke-a-claimed-email-credential.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.