Revoke compact credentials

Introduction

Compact or semantic compact credentials issued on the MATTR platform can be created as revocable, this allows Verifiers to obtain the revocation status of a credential as it is being presented. This is done in a way that preserves the privacy of the credential holder. 

This guide will demonstrate how to issue a compact or semantic compact credential that is revocable using a Revocation List, and how an issuer is able to revoke/un-revoke the issued credential. 

Prerequisites

You need the following in order to proceed with this tutorial: 

  • Access to the MATTR VII APIs

  • A signed and encoded compact or semantic compact credential represented as a string

If you’re experiencing any difficulties, contact us

Revocable compact credentials

A revocable compact credential contains a status property that points to a revocation list that contains the revocation status (revoked/not-revoked) of many credentials (up to 1,000,000). This ensures that when a Verifier requests a revocation list, the privacy of exactly which credential they are validating the revocation status for remains private i.e. the Issuer will not know who to or how often a credential is being presented.  When a revocable compact credential is issued, the bit value of the index in the revocation list is set to 0 by default. 

The following is an example of the status property. 

json
Copy to clipboard.
1"status": { 
2      "index": 43      "url": "https://9b03-122-57-56-69.ngrok.io/core/v2/credentials/compact/revocation-lists/f91bbef3-6898-4930-bca3-cf0d4b63e939https://9b03-122-57-56-69.ngrok.io/core/v2/credentials/compact/revocation-lists/f91bbef3-6898-4930-bca3-cf0d4b63e939" 
4}

Update revocation status

A credential can be revoked by setting the revocation status. The status can be set back to false to reactivate the credential.

Compact credential 

Request 

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/M2Cbq-3GRgu3aXR9YmMHcA/revocation-status
json
Copy to clipboard.
1{
2    "isRevoked": true
3}

where M2Cbq-3GRgu3aXR9YmMHcA is the id of the Compact Credential.

Response 

json
Copy to clipboard.
1{
2    "id": "M2Cbq-3GRgu3aXR9YmMHcA",
3    "isRevoked": true
4}

Semantic compact credential 

Request 

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b/revocation-status
json
Copy to clipboard.
1{
2    "isRevoked": true
3}

where urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b is the id of the Semantic Compact Credential.

Response 

json
Copy to clipboard.
1{
2    "id": "urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b",
3    "isRevoked": true
4}

The revocation list is cached for a certain amount of time. When verifying a credential with a newly updated revocation status, please allow time for the update to take effect.

Obtain revocation status

Retrieve the revocation status of a credential.

Compact credential 

Request 

http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/core/v2/credentials/compact/M2Cbq-3GRgu3aXR9YmMHcA/revocation-status

Response 

json
Copy to clipboard.
1{
2    "id": "M2Cbq-3GRgu3aXR9YmMHcA",
3    "isRevoked": true
4}

Semantic compact credential 

Request 

http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b/revocation-status

Response 

json
Copy to clipboard.
1{
2    "id": "urn:uuid:2e2fd5a2-f6cb-4793-bd70-69acaa08723b",
3    "isRevoked": true
4}

Revocation list

Every revocable credential issued will reference a revocation list, this is automatically created and held on the tenant for the Issuer. The revocation list can be obtained from a public endpoint as defined in the subject holder's credentials. 

Public revocation list discovery

Compact credential 

Request 
http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/core/v2/credentials/compact/revocation-lists
Response 
json
Copy to clipboard.
1{
2    "data": [
3        {
4            "id": "eea87efd-1fc1-4cc3-85c0-2fd490cf54a6",
5            "issuer": "did:web:example.nz",
6            "url": "https://YOUR_TENANT_URL/v2/credentials/compactc/revocation-lists/eea87efd-1fc1-4cc3-85c0-2fd490cf54a6"
7        }
8    ],
9    "nextCursor": "Y3JlYXRlZEF0PTIwMjItMDUtMTJUMDIlM0EyNiUzQTMzLjk5MlomaWQ9ZWVhODdlZmQtMWZjMS00Y2MzLTg1YzAtMmZkNDkwY2Y1NGE2"
10}

Semantic compact credential 

Request 
http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/revocation-lists
Response 
json
Copy to clipboard.
1{
2    "data": [
3        {
4            "id": "eea87efd-1fc1-4cc3-85c0-2fd490cf54a6",
5            "issuer": "did:web:example.nz",
6            "url": "https://YOUR_TENANT_URL/v2/credentials/compact-semantic/revocation-lists/eea87efd-1fc1-4cc3-85c0-2fd490cf54a6"
7        }
8    ],
9    "nextCursor": "Y3JlYXRlZEF0PTIwMjItMDUtMTJUMDIlM0EyNiUzQTMzLjk5MlomaWQ9ZWVhODdlZmQtMWZjMS00Y2MzLTg1YzAtMmZkNDkwY2Y1NGE2"
10}

Public revocation list

Retrieve the revocation list that contains the revocation status of a number of credentials.

Compact credential 

Request 
http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/core/v2/credentials/compact/revocation-lists/eea87efd-1fc1-4cc3-85c0-2fd490cf54a6

Semantic compact credential 

Request 
http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/revocation-lists/eea87efd-1fc1-4cc3-85c0-2fd490cf54a6

Response 

A binary file of the COSE Revocation List is returned.