1 of 10

Credential Statuses

The credentialStatus property is used to identify the status of a verifiable credential. It is an optional property (meaning when it's missing, the credential is not subject to any status change), but when specified, it includes the following mandatory fields:

id - a URI which identifies a location for the credential's status
type - an arbitrary string which identifies the type of the credential status (typically revocation or suspension)

Depending on the type, a credentialStatus property can contain additional fields, according to its model specification.

Currently, SSIKit supports the following credentialStatus methods:

StatusList2021Entry
SimpleCredentialStatus2022

More details on credentialStatus specification can be found at Verifiable Credential Data Model - Status.

StatusList2021Entry

StatusList2021Entry is a credentialStatus method by which the status of a verifiable credential can be checked. The basic idea of it is each issued credential has a corresponding position in a bit-string (also called the status list), having a value of either 0 - not revoked, or 1 - revoked. This status list is published by the issuer as a verifiable credential with a type that includes StatusList2021Credential.

The StatusList2021Entry credentialStatus contains the following fields:

id - a URL identifying the status information for the verifiable credential
type - StatusList2021Entry
statusPurpose - the purpose of the status entry (typically revocation or suspension)
statusListIndex - the bit position of the credential within the bit-string
statusListCredential - the URL of the StatusList2021Credential credential that encapsulates the bit-string

e.g.

{
  "id": "https://example.com/credentials/status/3#94567",
  "type": "StatusList2021Entry",
  "statusPurpose": "revocation",
  "statusListIndex": "94567",
  "statusListCredential": "https://example.com/credentials/status/3"
}

StatusList2021Credential

The StatusList2021Credential is a verifiable credential that encapsulates the bit-string information about all the credentials ever issued. The following fields have to be explicitly provided:

id - (optional) the URL to this credential (should match the statusListCredential value from StatusList2021Entry)
type - should contain StatusList2021Credential
credentialSubject
- type - StatusList2021
- statusPurpose - the purpose of the status credential (StatusList2021Entry should match this value)
- encodedList - the compressed and base64 encoded value of the bit-string

e.g.

{
  "id": "https://example.com/credentials/status/3",
  "type": ["VerifiableCredential", "StatusList2021Credential"],
  "credentialSubject": {
    "id": "https://example.com/status/3#list",
    "type": "StatusList2021",
    "statusPurpose": "revocation",
    "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
  },
  "other-verifiable-credential-properties": {}
}

More details about StatusList2021Entry and StatusList2021Credential can be found at Verifiable Credentials Status List v2021.

SimpleCredentialStatus2022

SimpleCredentialStatus2022 is a credentialStatus method by which the status of a verifiable credential can be checked. When a credential is issued with a SimpleCredentialStatus2022 credentialStatus type, it gets assigned a non-delegated revocation base-token. In order to check the status or revoke the verifiable credential, a delegated revocation derived-token is used.

Issue credentials with credentialStatus

In order to issue a verifiable credential with a credentialStatus, the statusType property of the proofConfig object should be provided (e.g. 'SimpleCredentialStatus2022', 'StatusList2021Entry', etc.). If no statusType is provided, the credential will be issued without any credentialStatus property.

Rest API interface

e.g. Issue a UniversityDegree credential having a StatusList2021Entry credentialStatus using the REST API interface issue endpoint: https://signatory.ssikit.walt.id/v1/credentials/issue. The request-body is presented below.

Command-line interface

e.g. Issue a UniversityDegree credential having a StatusList2021Entry credentialStatus using the command-line interface issue command: ssikit vc issue -h

REST API

All the revocation related endpoints are located under the revocations path: https://signatory.ssikit.walt.id/v1/revocations/:

check - check the verifiable credential revocation status
revoke - revoke a verifiable credential

Check is a low level function. For a high level check, refer to CredentialStatusPolicy.

Refer to the Issue with status section to learn about how to issue a verifiable credential with a credentialStatus property.

Check the status of a credential

Checking the status of a verifiable credential can be done using the REST API interface by supplying the credential as the body to the following POST request https://signatory.ssikit.walt.id/v1/revocations/check.

e.g. Execute the status check for a credential with a credentialStatus property

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/revocations/check' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "urn:uuid:3c89d819-49b0-41b0-a5c3-4386eb0cddbf",
    "issuer":
    {
        "id": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK"
    },
    "issuanceDate": "2023-04-28T15:35:36Z",
    "issued": "2023-04-28T15:35:36Z",
    "validFrom": "2023-04-28T15:35:36Z",
    "credentialSubject":
    {
        "id": "did:key:z6MkiWE3zZaTkDYLBwrPeZ94bXC9CnDVVeRcX12tncBh9q2X",
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        }
    },
    "credentialStatus":
    {
        "id": "https://signatory.ssikit.walt.id/v1/credentials/status/revocation#12",
        "statusListCredential": "https://signatory.ssikit.walt.id/v1/credentials/status/revocation",
        "statusListIndex": "12",
        "statusPurpose": "revocation",
        "type": "StatusList2021Entry"
    },
    "proof":
    {
        "type": "JsonWebSignature2020",
        "creator": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "created": "2023-04-28T15:35:38Z",
        "verificationMethod": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK#z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..Im6fYtggnBdooYMj0SNUEEZ6OGLfj7OHW6ZBaOusOR4HL6AqRdK7Sbm9vya8H_g6XQR8aeH1VXM5OTh5_P-eAA"
    }
}'

{
  "isRevoked": false
}

e.g. Execute the status check for a credential without a credentialStatus property

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/revocations/check' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "urn:uuid:22eefe7d-8467-46dc-9036-29d2d7597829",
    "issuer":
    {
        "id": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK"
    },
    "issuanceDate": "2023-04-28T15:42:31Z",
    "issued": "2023-04-28T15:42:31Z",
    "validFrom": "2023-04-28T15:42:31Z",
    "credentialSubject":
    {
        "id": "did:key:z6MkiWE3zZaTkDYLBwrPeZ94bXC9CnDVVeRcX12tncBh9q2X",
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        }
    },
    "proof":
    {
        "type": "JsonWebSignature2020",
        "creator": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "created": "2023-04-28T15:42:31Z",
        "verificationMethod": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK#z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..HDFwEbkhGCOUGUUYikbf-NfSokResd2vz1YGfJ_MpWb_Z0vqjJO4EGjw2FFtmpTOn66bFV_n4Y0aRKvaVkIvBg"
    }
}'

"Verifiable credential has no credential-status property"

Revoke a credential

Revoking a verifiable credential can be done using the REST API interface by supplying the credential as the body to the following POST request https://signatory.ssikit.walt.id/v1/revocations/revoke.

e.g. Execute the status check for a credential with a credentialStatus property

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/revocations/revoke' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "urn:uuid:3c89d819-49b0-41b0-a5c3-4386eb0cddbf",
    "issuer":
    {
        "id": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK"
    },
    "issuanceDate": "2023-04-28T15:35:36Z",
    "issued": "2023-04-28T15:35:36Z",
    "validFrom": "2023-04-28T15:35:36Z",
    "credentialSubject":
    {
        "id": "did:key:z6MkiWE3zZaTkDYLBwrPeZ94bXC9CnDVVeRcX12tncBh9q2X",
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        }
    },
    "credentialStatus":
    {
        "id": "https://signatory.ssikit.walt.id/v1/credentials/status/revocation#12",
        "statusListCredential": "https://signatory.ssikit.walt.id/v1/credentials/status/revocation",
        "statusListIndex": "12",
        "statusPurpose": "revocation",
        "type": "StatusList2021Entry"
    },
    "proof":
    {
        "type": "JsonWebSignature2020",
        "creator": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "created": "2023-04-28T15:35:38Z",
        "verificationMethod": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK#z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..Im6fYtggnBdooYMj0SNUEEZ6OGLfj7OHW6ZBaOusOR4HL6AqRdK7Sbm9vya8H_g6XQR8aeH1VXM5OTh5_P-eAA"
    }
}'

Http.Code = 200

e.g. Execute the status check for a credential without a credentialStatus property

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/revocations/revoke' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "urn:uuid:22eefe7d-8467-46dc-9036-29d2d7597829",
    "issuer":
    {
        "id": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK"
    },
    "issuanceDate": "2023-04-28T15:42:31Z",
    "issued": "2023-04-28T15:42:31Z",
    "validFrom": "2023-04-28T15:42:31Z",
    "credentialSubject":
    {
        "id": "did:key:z6MkiWE3zZaTkDYLBwrPeZ94bXC9CnDVVeRcX12tncBh9q2X",
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        }
    },
    "proof":
    {
        "type": "JsonWebSignature2020",
        "creator": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "created": "2023-04-28T15:42:31Z",
        "verificationMethod": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK#z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..HDFwEbkhGCOUGUUYikbf-NfSokResd2vz1YGfJ_MpWb_Z0vqjJO4EGjw2FFtmpTOn66bFV_n4Y0aRKvaVkIvBg"
    }
}'

Http.Code = 404

"Verifiable credential has no credential-status property"

CLI

A separate revocation command is available within the vc command for all revocation related operations.

ssikit vc revocation -h

check - check the verifiable credential revocation status
revoke - revoke a verifiable credential

Check is a low level function. For a high level check, refer to CredentialStatusPolicy.

Refer to the Issue with status section to learn about how to issue a verifiable credentials with a credentialStatus property.

Check the status of a credential

Checking the status of a verifiable credential can be done using the command-line interface with the following command:

ssikit vc revocation check {vc-filepath}

where {vc-filepath} is the path to the verifiable credential to be checked.

e.g. Verifiable Credential - vc.json

{
  "type":
  [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "@context":
  [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "urn:uuid:3c89d819-49b0-41b0-a5c3-4386eb0cddbf",
  "issuer":
  {
    "id": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK"
  },
  "issuanceDate": "2023-04-28T15:35:36Z",
  "issued": "2023-04-28T15:35:36Z",
  "validFrom": "2023-04-28T15:35:36Z",
  "credentialSubject":
  {
    "id": "did:key:z6MkiWE3zZaTkDYLBwrPeZ94bXC9CnDVVeRcX12tncBh9q2X",
    "degree":
    {
      "name": "Bachelor of Science and Arts",
      "type": "BachelorDegree"
    }
  },
  "credentialStatus":
  {
    "id": "http://127.0.0.1:7001/v1/credentials/status/revocation#12",
    "statusListCredential": "http://127.0.0.1:7001/v1/credentials/status/revocation",
    "statusListIndex": "12",
    "statusPurpose": "revocation",
    "type": "StatusList2021Entry"
  },
  "proof":
  {
    "type": "JsonWebSignature2020",
    "creator": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
    "created": "2023-04-28T15:35:38Z",
    "verificationMethod": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK#z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
    "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..Im6fYtggnBdooYMj0SNUEEZ6OGLfj7OHW6ZBaOusOR4HL6AqRdK7Sbm9vya8H_g6XQR8aeH1VXM5OTh5_P-eAA"
  }
}

e.g. Execute the status checking for a credential

ssikit vc revocation check vc.json

e.g. Status checking result

Checking revocation status for credential stored at: vc.json
Revocation status:
{
    "isRevoked" : false
}

Checking revocation status for credential stored at: vc-missing-status.json
Verifiable credential has no credential-status property

Revoke a credential

Revoking a verifiable credential can be done using the command-line interface with the following command:

ssikit vc revocation revoke {vc-filepath}

where {vc-filepath} is the path to the verifiable credential to be checked.

e.g. Verifiable Credential - vc.json

{
  "type":
  [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "@context":
  [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "urn:uuid:3c89d819-49b0-41b0-a5c3-4386eb0cddbf",
  "issuer":
  {
    "id": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK"
  },
  "issuanceDate": "2023-04-28T15:35:36Z",
  "issued": "2023-04-28T15:35:36Z",
  "validFrom": "2023-04-28T15:35:36Z",
  "credentialSubject":
  {
    "id": "did:key:z6MkiWE3zZaTkDYLBwrPeZ94bXC9CnDVVeRcX12tncBh9q2X",
    "degree":
    {
      "name": "Bachelor of Science and Arts",
      "type": "BachelorDegree"
    }
  },
  "credentialStatus":
  {
    "id": "http://127.0.0.1:7001/v1/credentials/status/revocation#12",
    "statusListCredential": "http://127.0.0.1:7001/v1/credentials/status/revocation",
    "statusListIndex": "12",
    "statusPurpose": "revocation",
    "type": "StatusList2021Entry"
  },
  "proof":
  {
    "type": "JsonWebSignature2020",
    "creator": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
    "created": "2023-04-28T15:35:38Z",
    "verificationMethod": "did:key:z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK#z6MkoHRK9dK81gFrGzwo6kygHW8KRoECGhLk5QJgNPYdzCTK",
    "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..Im6fYtggnBdooYMj0SNUEEZ6OGLfj7OHW6ZBaOusOR4HL6AqRdK7Sbm9vya8H_g6XQR8aeH1VXM5OTh5_P-eAA"
  }
}

e.g. Revoke the credential

ssikit vc revocation revoke vc.json

e.g. Revocation result

Revoking credential stored at: vc.json
Revocation result:
{
    "message" : "",
    "succeed" : true
}

Revoking credential stored at: vc-missing-status.json
Revocation result:
{
    "message" : "Verifiable credential has no credential-status property",
    "succeed" : false
}