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.

POST https://tenant.platform.mattr.global/v1/credentials

Request

{
"issuer": {
"id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
"name": "tenant.platform.mattr.global"
},
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://schema.org"
],
"subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
"type": [
"VerifiableCredential",
"Course"
],
"claims": {
"givenName": "Chris",
"familyName": "Shin",
"educationalCredentialAwarded": "Certificate Name"
},
"revocable": true
}

Response

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

{
"id": "e6c9b6a2-d87b-4be1-8b3a-f3dc13b44b5c",
"credential": {
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://schema.org",
"https://w3id.org/vc-revocation-list-2020/v1"
],
"type": [
"VerifiableCredential",
"Course"
],
"credentialStatus": {
"id": "https://tenant.platform.mattr.global/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3#4",
"type": "RevocationList2020Status",
"revocationListIndex": "4",
"revocationListCredential": "https://tenant.platform.mattr.global/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
},
"issuer": {
"id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
"name": "tenant.platform.mattr.global"
},
"credentialSubject": {
"id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
"givenName": "Chris",
"familyName": "Shin",
"educationalCredentialAwarded": "Certificate Name"
},
"issuanceDate": "2020-10-08T03:00:12.478Z",
"proof": {
"jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..PFXv7Kgc8tqxBELiLvPLgeksfo0hlE4adV3_zt6MRcyYY26FGxiB4ctAVez25JW86Z1o6EAbuGKVctMYB_psCw",
"type": "Ed25519Signature2018",
"created": "2020-10-08T03:00:12Z",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi#z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi"
}
}
},
"issuanceDate": "2020-10-08T03:00:12.478Z"
}

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.

POST https://tenant.platform.mattr.global/v1/credentials/e6c9b6a2-d87b-4be1-8b3a-f3dc13b44b5c/revocation-status
{
"isRevoked": true
}

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, the platform 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

GET
https://tenant.platform.mattr.global/v1/credentials/e6c9b6a2-d87b-4be1-8b3a-f3dc13b44b5c/revocation-status

Response

{
"isRevoked": true
}

If the credential is revoked, the returned isRevoked value will be true. If the credential id provided is not a revocable credential a 404 is returned.