Revoke a claimed email credential

Tutorial on how to revoke a claimed 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

• Valid Issuer ApiKey

• Valid JWT Access Token

• Valid role of Issuer Admin

• An ID of a valid clamed credential offer from Issuer API

To follow along, you can refer to the Issue an Email Credential tutorial. After completing the steps to issue a credential, you will also need to claim it (e.g., using the nChain Identity Wallet app) before proceeding with revocation.

Guide

1

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.

2

Prepare a valid claimed credential

Before revoking a credential, ensure you have the following:

1. Credential ID. Obtain the unique identifier for the credential. This ID was generated when the credential was created.

   • If the ID is lost, use the "Credential Offer Pagination" endpoint to retrieve a paginated list of all credentials.

curl --location '<ISSUER_API_BASE_URL>/private/credential-offers' \
--header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

• Claim Status: Verify that the credential has been claimed by a holder before proceeding with revocation. Use the "Retrieve Credential Offer" endpoint to fetch the credential's details. Check the status field to confirm that the credential has been claimed.

curl --location '<ISSUER_API_BASE_URL>/private/credential-offers/<CREDENTIAL_ID>' \
--header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

3

Revoke the credential

Using the Issuer API, you can revoke a credential by calling the Revoke endpoint. Provide the Credential 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.

curl --location --request PATCH '<ISSUER_API_BASE_URL>/private/credential-offers/revoke' \
--header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "revoke": [
        {
            "id": "<CREDENTIAL_ID>",
            "revocationReason": "email compromised"
        }
    ]
}'

Replace the placeholder values in <ISSUER_API_BASE_URL> and <JWT_ACCESS_TOKEN> with the actual values for your setup. For the revocation data, provide the real UUID value for <CREDENTIAL_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" endpoint.

View full API documentation for endpoint used in this section

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.