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:

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.

• revocationListIndex: References the index of this specific credential status in the Revocation 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:

• Revoke a credential: This will be used by the issuer to revoke (or unrevoke) any existing credentials.

• Retrieve a credential revocation status: This will be used by MATTR VII to retrieve the credential revocation status of a credential as part of a verification workflow.

• Retrieve a revocation list: This will be used by public verifiers to check the credential status of a credential as part of a verification workflow.

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:

  • The response when you created the credential.

  • The Credential Registry, as the credentialStatus object is stored as metadata.

Revoke a credential

Request

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

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.

1{
2  "isRevoked": true
3}

Response

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:

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

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):

1GET https://YOUR_TENANT_URL/v2/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3

Response

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

00010000000001111000000000000000000000001000001000000000100010011100000000000000000000000000000000000...

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