1 of 3

Token Status List

Get Started

Understanding Token Status List

Token Status List is a specification from the Internet Engineering Task Force, using JSON or CBOR encoded sets of bits and wrapping these as either a JSON Web Tokens (JWTs) or CBOR Web Tokens (CWTs), to comprise a full status list.

The .

Create Token Status List

Create a Token Status List JWT or CWT as a DID-Linked Resource (DLR), using cheqd Studio.

Users are able to create Token Status List entries on-ledger, which may be used to represent whether a Verifiable Credential is active, inactive or suspended. This implementation on cheqd is a derivation from the core spec made by cheqd to support a more decentralised and resilient approach to storing Token Status Lists.

Step 1: Set up your account

Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:

Step 2: Create a DID

Before you can create a Status List, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:

Step 3. Create your Status List JWT/CWT and save the file locally

Token Status Lists are JWT or CWT files that reference lists of bits formatted in JSON or CBOR.

Non-normative example for a Status List Token in JWT format

Non-normative example for a Status List Token in CWT format (not including the type header yet)

Save this file locally and call it something like statusListToken.json

Note that each JWT or CWT must be below ~45kb in size.

Step 4: Encode the file

Prepare a file with resource and encode it into base64, base64url or hex. On Unix systems, you can use the following command input:

Expected output:

Step 5: Set the resource name and type

DID-Linked Resources are grouped by having identical names and types. This means if you want to create a new version of the same Resource, you will need to specify the same name and type in the following request.

For Token Status Lists, the "type" MUST be: "TokenStatusList".

For example:

Step 6: Populate the request inputs and hit the API

Ensure that you link this Token Status List to the DID that you created in step 3. This will sign the resource with the same verification method keys in your DID Document, ensuring cryptographic integrity and Controllership of the Status List.

As a DID-Linked Resource, the Token Status List will have a fully resolvable DID URL which can be referenced within the body of Verifiable Credentials, and queried by verification policies to establish the status of the specific credential.

Step 7: Reference the Token Status List

Owing to the design of DID-Linked Resources, following the creation of the Token Status List, users are able to reference the specific version, or create a query to always fetch the latest version of the Token Status List.

Using a DID Resolver or the search DID endpoint, users can find the DID URL and unique resourceId of the Token Status List. The unique resourceId allows users to specify this exact version of the Token Status List.

In the DID Document Metadata, users should find "linkedResourceMetadata", like the following snippet:

Specific version of the Token Status List

Here, the "resourceURI" specifies the DID URL of the specific Token Status List that was created.

Latest version of the Token Status List

In order to reference the latest version of the Token Status List, the following construction needs to be used:

did:cheqd:<namespace>:<resourceCollectionId>?resourceName=<resourceName>&resourceType=<resourceType>

For example:

did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList

Token Status List at specific point in time

In order to reference the Token Status List at a particular point in time, the following construction needs to be used:

did:cheqd:<namespace>:<resourceCollectionId>?resourceName=<resourceName>&resourceType=<resourceType>&resourceVerionTime=<XMLDateTime>

For example:

did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList&resourceVersionTime=2023-02-22T06:58:18.61Z

Update Token Status List

Update a Token Status List JWT or CWT as a new DID-Linked Resource (DLR), using cheqd Studio.

Step 1. Manually create your new Status List JWT/CWT and save the file locally

Create a JWT or CWT file with the updated indices and bits for the updated Status List.

Non-normative example for a Status List Token in JWT format

Non-normative example for a Status List Token in CWT format (not including the type header yet)

Save this file locally and call it something like statusListTokenUPDATED.json

Note that each JWT or CWT must be below ~45kb in size.

Step 2: Encode the updated file

Prepare a file with resource and encode it into base64, base64url or hex. On Unix systems, you can use the following command input:

Expected output:

Step 3: Set the same Resource Name and Type

To create a new version you must use the same "name" and "type" for your resource, and ensure that the new Token Status List resource is being created underneath the same DID as your initial DID. You will also need to be logged into the same cheqd Studio account that you used to create the initial Token Status List to have access to the keys to sign the update.

For Token Status Lists, the "type" MUST be: "TokenStatusList".

For example:

Step 4: Populate the request inputs and hit the API

Create Token Status List

Create a Token Status List JWT or CWT as a DID-Linked Resource (DLR), using cheqd Studio.

Step 1: Set up your account

Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:

Step 2: Create a DID

Before you can create a Status List, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:

Step 3. Create your Status List JWT/CWT and save the file locally

Token Status Lists are JWT or CWT files that reference lists of bits formatted in JSON or CBOR.

Non-normative example for a Status List Token in JWT format

Non-normative example for a Status List Token in CWT format (not including the type header yet)

Save this file locally and call it something like statusListToken.json

Note that each JWT or CWT must be below ~45kb in size.

Step 4: Encode the file

Prepare a file with resource and encode it into base64, base64url or hex. On Unix systems, you can use the following command input:

Expected output:

Step 5: Set the resource name and type

For Token Status Lists, the "type" MUST be: "TokenStatusList".

For example:

Step 6: Populate the request inputs and hit the API

Step 7: Reference the Token Status List

In the DID Document Metadata, users should find "linkedResourceMetadata", like the following snippet:

Specific version of the Token Status List

Here, the "resourceURI" specifies the DID URL of the specific Token Status List that was created.

Latest version of the Token Status List

In order to reference the latest version of the Token Status List, the following construction needs to be used:

did:cheqd:<namespace>:<resourceCollectionId>?resourceName=<resourceName>&resourceType=<resourceType>

For example:

did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList

Token Status List at specific point in time

In order to reference the Token Status List at a particular point in time, the following construction needs to be used:

did:cheqd:<namespace>:<resourceCollectionId>?resourceName=<resourceName>&resourceType=<resourceType>&resourceVerionTime=<XMLDateTime>

For example:

did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList&resourceVersionTime=2023-02-22T06:58:18.61Z

Update Token Status List

Update a Token Status List JWT or CWT as a new DID-Linked Resource (DLR), using cheqd Studio.

Step 1. Manually create your new Status List JWT/CWT and save the file locally

Create a JWT or CWT file with the updated indices and bits for the updated Status List.

Non-normative example for a Status List Token in JWT format

Non-normative example for a Status List Token in CWT format (not including the type header yet)

Save this file locally and call it something like statusListTokenUPDATED.json

Note that each JWT or CWT must be below ~45kb in size.

Step 2: Encode the updated file

Prepare a file with resource and encode it into base64, base64url or hex. On Unix systems, you can use the following command input:

Expected output:

Step 3: Set the same Resource Name and Type

For Token Status Lists, the "type" MUST be: "TokenStatusList".

For example:

Step 4: Populate the request inputs and hit the API

Create a DID-Linked Resource.

post

/resource/create/{did}

This endpoint creates a DID-Linked Resource. As input, it can take the DID identifier and the resource parameters via a form, or the fully-assembled resource itself.

Authorizations

x-api-keystringRequired

Path parameters

didstringRequired

DID identifier to link the resource to.

Body

Input fields for DID-Linked Resource creation.

datastringRequired

Encoded string containing the data to be stored in the DID-Linked Resource.

encodingstring · enumRequired

Encoding format used to encode the data.

Possible values:

namestringRequired

Name of DID-Linked Resource.

typestringRequired

Type of DID-Linked Resource. This is NOT the same as the media type, which is calculated automatically ledger-side.

versionstringOptional

Optional field to assign a human-readable version in the DID-Linked Resource.

publicKeyHexsstring[]Optional

List of key references (publicKeys) which will be used for signing the message. The should be in hexadecimal format and placed in the wallet of current user.

Resolve a DID Document.

get

/did/search/{did}

Resolve a DID Document by DID identifier. Also supports DID Resolution Queries as defined in the .

Authorizations

x-api-keystringRequired

Path parameters

didstringRequired

DID identifier to resolve.

Example: did:cheqd:mainnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0

Query parameters

metadatabooleanOptional

Return only metadata of DID Document instead of actual DID Document.

versionIdstring · uuidOptional

Unique UUID version identifier of DID Document. Allows for fetching a specific version of the DID Document. See cheqd DID Method Specification for more details.

Example: 3ccde6ba-6ba5-56f2-9f4f-8825561a9860

versionTimestring · date-timeOptional

Returns the closest version of the DID Document at or before specified time. See DID Resolution handling for did:cheqd for more details.

Example: 1970-01-01T00:00:00Z

transformKeysstring · enumOptional

This directive transforms the Verification Method key format from the version in the DID Document to the specified format chosen below.

Possible values:

servicestringOptional

Query DID Document for a specific Service Endpoint by Service ID (e.g., service-1 in did:cheqd:mainnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1). This will typically redirect to the Service Endpoint based on DID Resolution specification algorithm.

Example: service-1

relativeRefstringOptional

Relative reference is a query fragment appended to the Service Endpoint URL. Must be used along with the service query property above. See DID Resolution specification algorithm for more details.

Example: /path/to/file

Create a DID-Linked Resource.

post

/resource/create/{did}

This endpoint creates a DID-Linked Resource. As input, it can take the DID identifier and the resource parameters via a form, or the fully-assembled resource itself.

Authorizations

x-api-keystringRequired

Path parameters

didstringRequired

DID identifier to link the resource to.

Body

Input fields for DID-Linked Resource creation.

datastringRequired

Encoded string containing the data to be stored in the DID-Linked Resource.

encodingstring · enumRequired

Encoding format used to encode the data.

Possible values:

namestringRequired

Name of DID-Linked Resource.

typestringRequired

Type of DID-Linked Resource. This is NOT the same as the media type, which is calculated automatically ledger-side.

versionstringOptional

Optional field to assign a human-readable version in the DID-Linked Resource.

publicKeyHexsstring[]Optional

List of key references (publicKeys) which will be used for signing the message. The should be in hexadecimal format and placed in the wallet of current user.

Responses

200

The request was successful.

application/json

resourceURIstringOptionalExample: did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47/resources/398cee0a-efac-4643-9f4c-74c48c72a14b

resourceCollectionIdstringOptionalExample: 55dbc8bf-fba3-4117-855c-1e0dc1d3bb47

resourceIdstringOptionalExample: 398cee0a-efac-4643-9f4c-74c48c72a14b

resourceNamestringOptionalExample: cheqd-issuer-logo

resourceTypestringOptionalExample: CredentialArtwork

mediaTypestringOptionalExample: image/png

resourceVersionstringOptionalExample: 1.0

checksumstringOptionalExample: a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559

createdstringOptionalExample: 2021-09-01T12:00:00Z

nextVersionIdstringOptionalExample: d4829ac7-4566-478c-a408-b44767eddadc

previousVersionIdstringOptionalExample: ad7a8442-3531-46eb-a024-53953ec6e4ff

400

A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.

401

Access token is missing or invalid

500

An internal error has occurred. Additional state information plus metadata may be available in the response body.

post

/resource/create/{did}

Responses

200

The request was successful.

application/json

resourceURIstringOptionalExample: did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47/resources/398cee0a-efac-4643-9f4c-74c48c72a14b

resourceCollectionIdstringOptionalExample: 55dbc8bf-fba3-4117-855c-1e0dc1d3bb47

resourceIdstringOptionalExample: 398cee0a-efac-4643-9f4c-74c48c72a14b

resourceNamestringOptionalExample: cheqd-issuer-logo

resourceTypestringOptionalExample: CredentialArtwork

mediaTypestringOptionalExample: image/png

resourceVersionstringOptionalExample: 1.0

checksumstringOptionalExample: a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559

createdstringOptionalExample: 2021-09-01T12:00:00Z

nextVersionIdstringOptionalExample: d4829ac7-4566-478c-a408-b44767eddadc

previousVersionIdstringOptionalExample: ad7a8442-3531-46eb-a024-53953ec6e4ff

400

A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.

401

Access token is missing or invalid

500

An internal error has occurred. Additional state information plus metadata may be available in the response body.

{
  "@context": "https://w3id.org/did-resolution/v1",
  "didDidResolutionMetadata": {
    "contentType": "application/did+ld+json",
    "retrieved": "2021-09-01T12:00:00Z",
    "did": {
      "didString": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
      "method": "cheqd",
      "methodSpecificId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47"
    }
  },
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
    "controller": [
      "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0"
    ],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#key-1",
        "type": "Ed25519VerificationKey2018",
        "controller": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
        "publicKeyBase58": "z6MkkVbyHJLLjdjU5B62DaJ4mkdMdUkttf9UqySSkA9bVTeZ"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#key-1"
    ],
    "service": [
      {
        "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1",
        "type": "LinkedDomains",
        "serviceEndpoint": [
          "https://example.com"
        ]
      }
    ]
  },
  "didDocumentMetadata": {
    "created": "2021-09-01T12:00:00Z",
    "deactivated": false,
    "updated": "2021-09-10T12:00:00Z",
    "versionId": "3ccde6ba-6ba5-56f2-9f4f-8825561a9860",
    "linkedResourceMetadata": [
      {
        "resourceURI": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47/resources/398cee0a-efac-4643-9f4c-74c48c72a14b",
        "resourceCollectionId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
        "resourceId": "398cee0a-efac-4643-9f4c-74c48c72a14b",
        "resourceName": "cheqd-issuer-logo",
        "resourceType": "CredentialArtwork",
        "mediaType": "image/png",
        "resourceVersion": "1.0",
        "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
        "created": "2021-09-01T12:00:00Z",
        "nextVersionId": "d4829ac7-4566-478c-a408-b44767eddadc",
        "previousVersionId": "ad7a8442-3531-46eb-a024-53953ec6e4ff"
      }
    ]
  }
}

{
  "@context": "https://w3id.org/did-resolution/v1",
  "didDidResolutionMetadata": {
    "contentType": "application/did+ld+json",
    "retrieved": "2021-09-01T12:00:00Z",
    "did": {
      "didString": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
      "method": "cheqd",
      "methodSpecificId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47"
    }
  },
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
    "controller": [
      "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0"
    ],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#key-1",
        "type": "Ed25519VerificationKey2018",
        "controller": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
        "publicKeyBase58": "z6MkkVbyHJLLjdjU5B62DaJ4mkdMdUkttf9UqySSkA9bVTeZ"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#key-1"
    ],
    "service": [
      {
        "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1",
        "type": "LinkedDomains",
        "serviceEndpoint": [
          "https://example.com"
        ]
      }
    ]
  },
  "didDocumentMetadata": {
    "created": "2021-09-01T12:00:00Z",
    "deactivated": false,
    "updated": "2021-09-10T12:00:00Z",
    "versionId": "3ccde6ba-6ba5-56f2-9f4f-8825561a9860",
    "linkedResourceMetadata": [
      {
        "resourceURI": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47/resources/398cee0a-efac-4643-9f4c-74c48c72a14b",
        "resourceCollectionId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
        "resourceId": "398cee0a-efac-4643-9f4c-74c48c72a14b",
        "resourceName": "cheqd-issuer-logo",
        "resourceType": "CredentialArtwork",
        "mediaType": "image/png",
        "resourceVersion": "1.0",
        "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
        "created": "2021-09-01T12:00:00Z",
        "nextVersionId": "d4829ac7-4566-478c-a408-b44767eddadc",
        "previousVersionId": "ad7a8442-3531-46eb-a024-53953ec6e4ff"
      }
    ]
  }
}

Token Status List

hashtagGet Started

hashtagUnderstanding Token Status List

Create Token Status List

hashtagStep 1: Set up your account

hashtagStep 2: Create a DID

hashtagStep 3. Create your Status List JWT/CWT and save the file locally

hashtagStep 4: Encode the file

hashtagStep 5: Set the resource name and type

hashtagStep 6: Populate the request inputs and hit the API

hashtagStep 7: Reference the Token Status List

hashtagSpecific version of the Token Status List

hashtagLatest version of the Token Status List

hashtagToken Status List at specific point in time

Update Token Status List

hashtagStep 1. Manually create your new Status List JWT/CWT and save the file locally

hashtagStep 2: Encode the updated file

hashtagStep 3: Set the same Resource Name and Type

hashtagStep 4: Populate the request inputs and hit the API

Token Status List

hashtagGet Started

hashtagUnderstanding Token Status List

Create Token Status List

hashtagStep 1: Set up your account

hashtagStep 2: Create a DID

hashtagStep 3. Create your Status List JWT/CWT and save the file locally

hashtagStep 4: Encode the file

hashtagStep 5: Set the resource name and type

hashtagStep 6: Populate the request inputs and hit the API

hashtagStep 7: Reference the Token Status List

hashtagSpecific version of the Token Status List

hashtagLatest version of the Token Status List

hashtagToken Status List at specific point in time

Update Token Status List

hashtagStep 1. Manually create your new Status List JWT/CWT and save the file locally

hashtagStep 2: Encode the updated file

hashtagStep 3: Set the same Resource Name and Type

hashtagStep 4: Populate the request inputs and hit the API

hashtagCreate a DID-Linked Resource.

hashtagResolve a DID Document.

hashtagCreate a DID-Linked Resource.

Get Started

Understanding Token Status List

Step 1: Set up your account

Step 2: Create a DID

Step 3. Create your Status List JWT/CWT and save the file locally

Step 4: Encode the file

Step 5: Set the resource name and type

Step 6: Populate the request inputs and hit the API

Step 7: Reference the Token Status List

Specific version of the Token Status List

Latest version of the Token Status List

Token Status List at specific point in time

Step 1. Manually create your new Status List JWT/CWT and save the file locally

Step 2: Encode the updated file

Step 3: Set the same Resource Name and Type

Step 4: Populate the request inputs and hit the API

Get Started

Understanding Token Status List

Step 1: Set up your account

Step 2: Create a DID

Step 3. Create your Status List JWT/CWT and save the file locally

Step 4: Encode the file

Step 5: Set the resource name and type

Step 6: Populate the request inputs and hit the API

Step 7: Reference the Token Status List

Specific version of the Token Status List

Latest version of the Token Status List

Token Status List at specific point in time

Step 1. Manually create your new Status List JWT/CWT and save the file locally

Step 2: Encode the updated file

Step 3: Set the same Resource Name and Type

Step 4: Populate the request inputs and hit the API

Create a DID-Linked Resource.

Resolve a DID Document.

Create a DID-Linked Resource.