Revoke a Web Credential

To configure a Web Credential as revoable, you need to set its revocable property to true when you create it. This will result in the following:

  • https://w3id.org/vc-revocation-list-2020/v1 is injected into their @context object. This references the JSON-LD definition of the credentialStatus object.

  • They include the following credentialStatus object:

json
Copy to clipboard.
1    "credentialStatus": {
2        "id": "https://YOUR_TENANT_URL/v2/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3#4",
3        "type": "RevocationList2020Status",
4        "revocationListIndex": "4",
5        "revocationListCredential": "https://tenant.vii.mattr.global/v2/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
6    }
  • id: This is a unique identifier of this credential's status. It is the concatenation of the revocationListIndex and revocationListCredential fields.

  • type: Indicates the credential status type. This example uses RevocationList2020Status in alignment with

  • revocationListIndex: References the index of this specific credential status in the Reovcation List.

  • revocationListCredential: Every revocable credential will reference a Revocation List that is automatically created and held on the issuer's tenant. This list can be used by external verifiers to validate the credential status. This field references the Reovcation List which holds the revocation status for this specific credential.

All Credentials issued via the OpenID4VCI issuance workflow are not revocable by default.

All credentials issued via the OIDC Bridge issuance workflow are revocable by default.

This guide will walk you through the following operations:

You can also check out this video for a hands-on approach:

Web Credentials are automatically revoked when they are deleted from the Credential Registry.

Prerequisites

  • Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

  • You will need the id of a revocable Web Credential. You can obtain it from either:

Revoke a credential

Request

Make a request of the following structure to revoke a Web Credential:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v2/credentials/web-semantic/{id}/revocation-status
  • Replace {id} with the id of the Web Credential you wish to revoke.

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

Response

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

Once isRevoked is set to true, this had been revoked and will not be verified as valid.

You can make a similar request with isRevoked set to false to unrevoke a credential.

Retrieve a credential revocation status

Request

Make a request of the following structure to retrieve the revocation status of a Web Credential:

http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/v2/credentials/web-semantics/{id}/revocation-status
  • Replace {id} with the id of the Web Credential you to retrieve the revocation status for.

Response

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

Retrieve a Revocation List

The Revocation List can be retrieved from the credentialStatus property defined in the credential or saved as metadata in the Credential Registry. This will be a publicly available endpoint. Generally Issuer do not need to view this data and a MATTR VII Verifier will obtain this data automatically, so this endpoint will mainly be consumed by external verifiers.

Request

Make a request of the following structure to retrieve a Revocation List (this is the same URL you will find in the credentialStatus.revocationListCredential property):

http
Copy to clipboard.
1GET https://YOUR_TENANT_URL/v2/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3

Response

json
Copy to clipboard.
1{
2    "id": "https://YOUR_TENANT_URL/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3",
3    "@context": [
4        "https://www.w3.org/2018/credentials/v1",
5        "https://w3id.org/vc-revocation-list-2020/v1"
6    ],
7    "type": [
8        "VerifiableCredential",
9        "RevocationList2020Credential"
10    ],
11    "issuer": "did:web:organization.com",
12    "credentialSubject": {
13        "type": "RevocationList2020",
14        "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
15    },
16    "issuanceDate": "2020-10-04T22:20:48.861Z",
17    "expirationDate": "2023-02-21T06:44:28.952Z",
18    "proof": {
19        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..iwouae64R3vVidRasfUUyKJ3EBj7PhffS_weHBOuzfNJeFAxHEB3rTQKGFQbkJozlYuMH0dRRk8rB9dvfjJECg",
20        "type": "Ed25519Signature2018",
21        "created": "2020-10-04T22:20:48Z",
22        "proofPurpose": "assertionMethod",
23        "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
24    }
25}

The returned revocation list is in the form of a JSON-LD based verifiable credential.

  • issuer: This is identical to the credential's issuer's DID.

  • credentialSubject.encodedList: This contains the encoded Revocation List. MATTR VII automatically decodes this list and looking up the value by the credentialStatus.revocationListIndex value:

    • 1: Revoked.

    • 0: Un-revoked.

Decoded Revocation List example

Copy to clipboard.
00010000000001111000000000000000000000001000001000000000100010011100000000000000000000000000000000000...

Index 4 of the list indicates that this credential is revoked.