How to revoke an mDoc

This guide can be used to perform the following common revocation operations:

Revoke an mDoc.
Retrieve an mDoc’s revocation status.
Create a Status list configuration

Prerequisites

The credentialId of a signed mDoc. Note that this mDoc must have includeStatus set to true. You can retrieve the credentialId in one of two ways:
- When you configure a Webhook that is triggered when an mDoc is issued via OID4VCI you can capture its credentialId from the response.
- Query the Retrieve all users credentials data endpoint and use the id from the response.

Revoke an mDoc

Request

Make a request of the following structure to revoke an mDoc:

HTTP

POST /v2/credentials/mobile/{credentialId}/status

credentialId : Replace with the credentialId of the mDoc you wish to revoke.

Request body

JSON

{
    "status": "invalid"
}

Once an mDoc status is set to invalid, it cannot be updated back to valid. You can make a similar request with status set to suspended to temporarily revoke an mDoc.

Response

JSON

{
    "status": "invalid"
}

status : Indicates the current status for this mDoc. When set to invalid or suspended the credential will not be verified as valid.

Status list tokens can be cached for a certain amount of time, depending on the configured ttl and exp. Updating a status might take some time to reflect in verification workflows.

Retrieve an mDoc’s status

Request

Make a request of the following structure to retrieve the status of an mDoc:

HTTP

GET /v2/credentials/mobile/{credentialId}/status

credentialId : Replace with the id of the mDoc you wish to check the status for.

Response

JSON

{
    "status": "valid"
}

status : Indicates the current status for this mDoc. When set to invalid or suspended the credential will not be verified as valid.

Create a Status list configuration

Request

Make a request of the following structure to create a Status list configuration:

HTTP

POST /v2/credentials/mobile/status-lists/configurations

Request body

JSON

{
    "docType": "DriverLicence",
    "timeToLiveDuration": {
        "weeks": 4,
        "days": 2,
        "hours": 10,
        "minutes": 20,
        "seconds": 30
    },
    "expiryDuration": {
        "weeks": 4,
        "days": 2,
        "hours": 10,
        "minutes": 20,
        "seconds": 30
    }
}

docType : Status list configurations are unique per docType on your tenant. This value must match the type set when creating an mDoc credential configuration.
timeToLiveDuration : Specifies a duration in any combination of weeks, days, hours, minutes and/or seconds. This value is used to calculate the ttl of a signed Status list token, which indicates the recommended duration the relying party should use the token before retrieving a new one.
expiryDuration : Specifies a duration in any combination of weeks, days, hours, minutes and/or seconds. This values is used to calculate the exp of a signed Status list token, which determines when the token expires and the relying party can no longer use it to check mDocs’ status.

🎓 Tutorial CWT