# Create Token Status List 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:
Set up your accountSet up your account with cheqd Studio and log in to start using the APIs.set-up-account
## 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:
Create an Issuer DIDCreate a W3C conformant DID on cheqd using the did:cheqd DID Method.create-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 ```json { "alg": "ES256", "kid": "12", "typ": "statuslist+jwt" } . { "exp": 2291720170, "iat": 1686920170, "iss": "https://example.com", "status_list": { "bits": 1, "lst": "eNrbuRgAAhcBXQ" }, "sub": "https://example.com/statuslists/1" } ```
Non-normative example for a Status List Token in CWT format (not including the type header yet) ```json d28453a20126106e7374617475736c6973742b637774a1044231325860a502782168 747470733a2f2f6578616d706c652e636f6d2f7374617475736c697374732f310173 68747470733a2f2f6578616d706c652e636f6d061a648c5bea041a8898dfea19fffe 56a2646269747301636c73744a78dadbb918000217015d58400f2ca3772e10b09d5d 6ed56461f7cba1a816c6234072d1bb693db277048e5db5a4e64444492a9b781d6c7a c9714db99cc7aadb3812ec90cab7794170bab5b473 ```
Save this file locally and call it something like `statusListToken.json` {% hint style="info" %} Note that each JWT or CWT must be **below \~45kb in size**. {% endhint %} ## 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: ```bash $ base64 -w 0 resource.json ``` Expected output: ```bash $ base64 -w 0 resource.json SGVsbG8sIHdvcmxk ``` ## 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: ```json { "data": "SGVsbG8sIHdvcmxk", "encoding": "base64url", "name": "DegreeCredentialStatus", "type": "TokenStatusList" } ``` ## 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. ## Create a DID-Linked Resource. > 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. ```json {"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"DID-Linked Resources (DLRs)"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"CreateResourceRequest":{"description":"Input fields for DID-Linked Resource creation.","type":"object","additionalProperties":false,"required":["name","type","data","encoding"],"properties":{"data":{"description":"Encoded string containing the data to be stored in the DID-Linked Resource.","type":"string"},"encoding":{"description":"Encoding format used to encode the data.","type":"string","enum":["base64url","base64","hex"]},"name":{"description":"Name of DID-Linked Resource.","type":"string"},"type":{"description":"Type of DID-Linked Resource. This is NOT the same as the media type, which is calculated automatically ledger-side.","type":"string"},"alsoKnownAs":{"description":"Optional field to assign a set of alternative URIs where the DID-Linked Resource can be fetched from.","type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"description":{"type":"string"}}}},"version":{"description":"Optional field to assign a human-readable version in the DID-Linked Resource.","type":"string"},"publicKeyHexs":{"description":"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.","type":"array","items":{"type":"string"}}}},"ResourceMetadata":{"type":"object","properties":{"resourceURI":{"type":"string"},"resourceCollectionId":{"type":"string"},"resourceId":{"type":"string"},"resourceName":{"type":"string"},"resourceType":{"type":"string"},"mediaType":{"type":"string"},"resourceVersion":{"type":"string"},"checksum":{"type":"string"},"created":{"type":"string"},"nextVersionId":{"type":"string"},"previousVersionId":{"type":"string"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/resource/create/{did}":{"post":{"tags":["DID-Linked Resources (DLRs)"],"summary":"Create a DID-Linked Resource.","description":"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.","parameters":[{"in":"path","name":"did","description":"DID identifier to link the resource to.","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CreateResourceRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/CreateResourceRequest"}}}},"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceMetadata"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}} ``` ## 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. ## Resolve a DID Document. > Resolve a DID Document by DID identifier. Also supports DID Resolution Queries as defined in the \W3C](https://w3c-ccg.github.io/did-resolution/">W3C) DID Resolution specification\. ```json {"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Decentralized Identifiers (DIDs)"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"DidResolution":{"type":"object","properties":{"@context":{"type":"string"},"didDidResolutionMetadata":{"$ref":"#/components/schemas/DidResolutionMetadata"},"didDocument":{"$ref":"#/components/schemas/DidDocument"},"didDocumentMetadata":{"$ref":"#/components/schemas/DidDocumentMetadata"}}},"DidResolutionMetadata":{"type":"object","properties":{"contentType":{"allOf":[{"$ref":"#/components/schemas/ContentType"}]},"retrieved":{"type":"string"},"did":{"$ref":"#/components/schemas/DidProperties"}}},"ContentType":{"type":"string","enum":["application/did+json","application/did+ld+json","application/ld+json","application/json"]},"DidProperties":{"type":"object","properties":{"didString":{"type":"string"},"method":{"type":"string"},"methodSpecificId":{"type":"string"}}},"DidDocument":{"description":"This input field contains either a complete DID document, or an incremental change (diff) to a DID document. See Universal DID Registrar specification.","type":"object","properties":{"@context":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"controllers":{"type":"array","items":{"type":"string"}},"verificationMethod":{"type":"array","items":{"$ref":"#/components/schemas/VerificationMethod"}},"service":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"authentication":{"type":"array","items":{"type":"string"}},"assertionMethod":{"type":"array","items":{"type":"string"}},"capabilityInvocation":{"type":"array","items":{"type":"string"}},"capabilityDelegation":{"type":"array","items":{"type":"string"}},"keyAgreement":{"type":"array","items":{"type":"string"}}}},"VerificationMethod":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"controller":{"type":"string"},"publicKeyMultibase":{"type":"string"},"publicKeyJwk":{"type":"array","items":{"type":"string"}}}},"Service":{"description":"Communicating or interacting with the DID subject or associated entities via one or more service endpoints. See DID Core specification for more details.","type":"object","properties":{"id":{"description":"DID appended with Service fragment ID (e.g., `#service-1` in `did:cheqd:mainnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1`)","type":"string"},"type":{"description":"Service type as defined in DID Specification Registries.","type":"string"},"serviceEndpoint":{"description":"Service endpoint as defined in DID Core Specification.","type":"array","items":{"type":"string"}},"priority":{"description":"(Optional) Priority of the service endpoint, used for distinction when multiple did-communication service endpoints are present in a single DID document.","type":"integer"},"recipientKeys":{"description":"(Optional) List of recipient keys used to denote the default recipients of an endpoint.","type":"array","items":{"type":"string"}},"routingKeys":{"description":"(Optional) List of routing keys used to used to denote the individual routing hops in between the sender and recipients.","type":"array","items":{"type":"string"}},"accept":{"description":"(Optional) List of media types that the service endpoint accepts.","type":"array","items":{"type":"string"}}}},"DidDocumentMetadata":{"type":"object","properties":{"created":{"type":"string"},"deactivated":{"type":"boolean"},"updated":{"type":"string"},"versionId":{"type":"string"},"linkedResourceMetadata":{"type":"array","items":{"$ref":"#/components/schemas/ResourceMetadata"}}}},"ResourceMetadata":{"type":"object","properties":{"resourceURI":{"type":"string"},"resourceCollectionId":{"type":"string"},"resourceId":{"type":"string"},"resourceName":{"type":"string"},"resourceType":{"type":"string"},"mediaType":{"type":"string"},"resourceVersion":{"type":"string"},"checksum":{"type":"string"},"created":{"type":"string"},"nextVersionId":{"type":"string"},"previousVersionId":{"type":"string"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/did/search/{did}":{"get":{"tags":["Decentralized Identifiers (DIDs)"],"summary":"Resolve a DID Document.","description":"Resolve a DID Document by DID identifier. Also supports DID Resolution Queries as defined in the W3C DID Resolution specification.","parameters":[{"in":"path","name":"did","description":"DID identifier to resolve.","schema":{"type":"string"},"required":true},{"in":"query","name":"metadata","description":"Return only metadata of DID Document instead of actual DID Document.","schema":{"type":"boolean"}},{"in":"query","name":"versionId","description":"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.","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"versionTime","description":"Returns the closest version of the DID Document *at* or *before* specified time. See DID Resolution handling for `did:cheqd` for more details.","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"transformKeys","description":"This directive transforms the Verification Method key format from the version in the DID Document to the specified format chosen below.","schema":{"type":"string","enum":["Ed25519VerificationKey2018","Ed25519VerificationKey2020","JsonWebKey2020"]}},{"in":"query","name":"service","description":"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.","schema":{"type":"string"}},{"in":"query","name":"relativeRef","description":"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.","schema":{"type":"string"}}],"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DidResolution"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}} ``` In the DID Document Metadata, users should find "linkedResourceMetadata", like the following snippet: ```json "linkedResourceMetadata": [ { "resourceURI": "did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d/resources/4e1104f9-2ee9-4bde-adc2-ab8ba72b124a", "resourceCollectionId": "0a5b94d0-a417-48ed-a6f5-4abc9e95888d", "resourceId": "4e1104f9-2ee9-4bde-adc2-ab8ba72b124a", "resourceName": "DegreeCredentialStatus", "resourceType": "TokenStatusList", "mediaType": "application/json", "resourceVersion": "", "created": "2023-03-24T12:13:45Z", "checksum": "6819aaecd4073173b159fedf8077c38e14939d03d58e7f4e2a0ddfe034eb2ed4", "previousVersionId": null, "nextVersionId": null } ``` ### 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::?resourceName=&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::?resourceName=&resourceType=&resourceVerionTime=` For example: `did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList&resourceVersionTime=2023-02-22T06:58:18.61Z`