Create & Update Revocable Credentials

Overview

This tutorial explains how to create a credential that can be revoked and how to update the revocation status of the credential.

Create a revocable credential

To create a revocable credential, set the revocable attribute to true.

All Credentials issued via the OIDC Bridge will be revocable by default.

http
Copy to clipboard.
1 POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials

Request

json
Copy to clipboard.
1{
2  "issuer": {
3    "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
4    "name": "YOUR_TENANT_SUBDOMAIN.vii.mattr.global"
5  },
6  "@context": [
7    "https://www.w3.org/2018/credentials/v1",
8    "https://schema.org"
9  ],
10  "subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
11  "type": [
12    "VerifiableCredential",
13    "CourseCredential"
14  ],
15  "claims": {
16    "givenName": "Chris",
17    "familyName": "Shin",
18    "educationalCredentialAwarded": "Certificate Name"
19  },
20  "revocable": true
21}

Response

The resulting credential will have a credentialStatus object pointing to the revocation list.

json
Copy to clipboard.
1{
2  "id": "e6c9b6a2-d87b-4be1-8b3a-f3dc13b44b5c",
3  "credential": {
4    {
5      "@context": [
6        "https://www.w3.org/2018/credentials/v1",
7        "https://schema.org",
8        "https://w3id.org/vc-revocation-list-2020/v1"
9      ],
10      "type": [
11        "VerifiableCredential",
12        "CourseCredential"
13      ],
14      "credentialStatus": {
15        "id": "https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3#4",
16        "type": "RevocationList2020Status",
17        "revocationListIndex": "4",
18        "revocationListCredential": "https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
19      },
20      "issuer": {
21        "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
22        "name": "YOUR_TENANT_SUBDOMAIN.vii.mattr.global"
23      },
24      "credentialSubject": {
25        "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
26        "givenName": "Chris",
27        "familyName": "Shin",
28        "educationalCredentialAwarded": "Certificate Name"
29      },
30      "issuanceDate": "2020-10-08T03:00:12.478Z",
31      "proof": {
32        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..PFXv7Kgc8tqxBELiLvPLgeksfo0hlE4adV3_zt6MRcyYY26FGxiB4ctAVez25JW86Z1o6EAbuGKVctMYB_psCw",
33        "type": "Ed25519Signature2018",
34        "created": "2020-10-08T03:00:12Z",
35        "proofPurpose": "assertionMethod",
36        "verificationMethod": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi#z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
37      }
38    }
39  },
40  "issuanceDate": "2020-10-08T03:00:12.478Z"
41}

https://w3id.org/vc-revocation-list-2020/v1 was automatically added to the @context, which defines the JSON-LD definition of the credentialStatus object.

The credentialStatus contains the revocation list information.

The id of the credentialStatus uniquely defines the credential status.

The RevocationList2020Status type indicates that the credential status is defined by a revocation list.

The revocationListIndex points to the location of the bit indicating if the credential is revoked or not.

The revocationListCredential contains the URL to obtain the revocation list.

Revoke a credential

In order to revoke a Credential as an Issuer, you need to provide the id of the credential to be revoked.

Credential ID's can be found using the Credential Registry, the credentialStatus property is stored as meta-data for reference.

Using the Set credential revocation status endpoint, set isRevoked to true in the request body.

http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials/e6c9b6a2-d87b-4be1-8b3a-f3dc13b44b5c/revocation-status

json
Copy to clipboard.
1{
2  "isRevoked": true
3}

If the credential id provided is not a revocable credential a 404 is returned.

When a revoked credential is being presented as per the Verify a Credential tutorial, MATTR VII will prevent the credential claims from being presented to the relying party.

Setting to Un-revoked

Revoked credentials can be made un-revoked by setting the isRevoked to false. This change is immediate, however there may be a slight delay of a few seconds for processing and caching to refresh.

Check the revocation status of a Credential

To obtain the revocation status of a Credential that you have issued, you need to provide the id of that Credential.

Credential ID's can be found using the Credential Registry, revocable Credentials also display their credentialStatus property information for reference.

Call the Retrieve credential revocation status endpoint with the credential id

http
Copy to clipboard.
1GET
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials/e6c9b6a2-d87b-4be1-8b3a-f3dc13b44b5c/revocation-status

Response

json
Copy to clipboard.
1{
2  "isRevoked": true
3}