Revoking Credentials

Revoking a credential means invalidating a credential so that when the credential is shared as part of a Verification Presentation the share fails. Issuers of credentials need this control so that if the data associated with an issued credential changes then it needs to be ensured the original data cannot be used. e.g. when an employee leaves your organisation you need to be able to ensure credentials issued to the employee associated with their employment arre revoked and no longer valid.

For verifiers the ability to revoke credentials gives confidence that credentials can be trusted so long as they have not expired.

Revoking Credentials in Cenda

In order to support revocation Cenda requires that the attribute SerialNumber is included all issuance templates. Cenda uses this attribute as a credential index for revocation in Microsoft Verified ID. The SerialNumber can be generated by the issuer and included in the idTokenHint, or if not included Cenda will generate the SerialNumber as GUID - the SerialNumber is returned in the set of claims for an issued credential.

Issuers must maintain a record of the SerialNumber attributes in order that the issuer can subsequently a credential.

Cenda provides the following endpoints detailed in Cenda's Configuration API Swagger Documentation to support revocation.

Revoke requested credential endpoint

POST /api/Revocation/revoke

Revoke requested credential request headers

Header	Value
Authorization	Bearer `access_token`

Revoke requested credential request URL parameters

There are no URL parameters needed for this call.

Revoke requested credential request body parameters

Parameter	Type	Required	Description
organisationId	string	Yes	The id of your organisation that issued the credential.
credentialTemplateName	string	Yes	The name of the credential template which was used to issue credential.
serialNumber	string	Yes	The SerialNumber of the credential to revoke.
revocationReason	string	No	The reason for revoking the credential (max 100chars).

Revoke requested credential request returns

A successful call will return a 204 No Content status code.

Note

It can take up to 15 minutes for a revoked credential to be fully revoked within Microsoft Verified ID.

An unsuccessful call will return an error message which should highlight the parameter(s) that needs checking.

{
  "type": "string",
  "title": "string",
  "status": 0,
  "traceId": "string",
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ]
  },
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
}

If any values are invalid or missing, an error response will be returned with a message highlighting the area that needs checking.

In this example, the value for the name property is invalid in the body. The error message returned shows that in the errors property.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-d3f24a539b9abb3466fcaf8543ca5001-2aa856a36c27004c-00",
  "errors": {
    "$.name": [
      "The JSON value could not be converted to System.String."
    ]
  }
}

Revoke requested credential by client endpoint

POST /api/Revocation/revokeCredential