The user is required to Log In to our cheqd Studio portal and then access their API key to authenticate with our APIs. The API key guards the API from unauthorized access and is required for both testing production environments.

Step 1: Get started with cheqd Studio

Head to our cheqd Studio and click Get Started.

Step 2: Create your account

cheqd Studio uses a third party service called LogTo to handle user authentication and login. This allows users to create new accounts as well as sign in using their email, Google single sign-on, or Discord login.

Step 3: Create a new API key and authenticate with cheqd Studio APIs

Step 4: Start using cheqd

Get started with our tutorials for cheqd Studio functionality.

Step 5: Select a Billing plan

You will be able to get started for free on our free trial, but following the expiry of the free trial, users need to sign up for a paid billing plan. cheqd Studio billing uses Stripe as a payments processor and users will need to input their card information to initiate a billing plan.

cheqd is a purpose-built network for decentralised identity. This documentation site provides technical and product information for all identity features & functionality on the cheqd network.

Integrate with cheqd

cheqd maintains an array of products and packages with varying levels of integration complexity to allow its partners and customers to have a variety of ways of plugging into cheqd's identity functionality. Via these different packages, customers and partners can create cheqd DIDs, DID-Linked Resources, Status Lists, Trust Registries and Schemas, as well as use cheqd's Credential Payments model, with different levels of integration effort and flexibility.

There are three core ways of integrating and building with cheqd:

What functionality does cheqd offer?

cheqd's identity functionality is fully standards compliant, ensuring interoperability and no vendor lock-in. cheqd's tooling and different product offerings offer a variety of building blocks for any Trusted Data Market.

Industry Standard DID Support

If you want to utilise cheqd DIDs or DID-Linked Resources within applications without a specific cheqd integration, you can incorporate a Universal Registrar or Universal Resolver driver to support did:cheqd alongside other commonly adopted DID methods.

Get started with cheqd Studio

cheqd Studio is the easiest route to get started with cheqd's identity functionality, or for testing with very low integration effort. Using simple REST APIs, it is possible to integrate cheqd Studio in a few lines of code.

Under the hood, cheqd Studio utilises the Veramo SDK cheqd Plugin, providing the most feature complete set of functionality and tooling.

If you'd rather build a deeper integration using a Software Development Kit (SDK) or lower level package, we've created a simple diagram to show how our packages are structured below.

Understanding cheqd's capabilities

cheqd supports a wide array of standards and protocols via different Software Development Kits (SDKs) and integrations.

Understanding the structure of cheqd's packages

One of cheqd's primary motives is to make itself accessible to the widest set of identity applications possible. To accomplish this, cheqd has built a flexible set of packages and tooling to accommodate its identity capabilities into a broad set of external SDKs and applications.

These can be represented through the visual below:

Get involved

The cheqd Discord is our primary chat channel for the open-source community, software developers, and node operators.

Please reach out to us there for discussions, help, and feedback on the project.

🙋 Find us elsewhere

cheqd Studio currently is setup to work with the Verida Wallet. In 2024, we will be building compatibility with a full suite of other digital identity wallets.

Verida Wallet

Subject DID

On the "Profile" tab, you will see your did:vda address under the section "DID".

For example: "did:vda:testnet:0xD7477C4a75143Af16A967381d09650A533Bd0DD7"

Rendering credentials

Credentials stored with the credential schema will automatically be rendered in the Verida Wallet as a credential. This custom display includes:

1. A scannable QR code

2. The profile icon of the Verida DID that issued / signed the credential

3. A tick of approval indicating the credential has been verified

Users may exhaust their usage limits in their cheqd Studio billing plan, but may want to continue using the Studio before their usage limits refresh. Therefore, users can manually top up their account with CHEQ tokens to use any APIs that involve a ledger-write, e.g:

1. Creating, Updating or Deactivating DIDs

2. Creating unencrypted or encrypted Status Lists

3. Creating Trust Registries

4. Creating other DID-Linked Resources

Step 1: Locate your cheqd address (for CHEQ)

The following API can be used to fetch the new account information:

• customer_id is used as an identifier for the particular customer using cheqd Studio. It is generated as a sub-field of the JWT token used in the authorization header.

• cheqd_account is used to pay for identity transactions on either testnet or mainnet. A cheqd account is automatically generated when a new customer_id is generated.

Step 2: Adding CHEQ tokens to your account

Users will need to add our token, CHEQ, to their cheqd_account on mainnet in order to be able to use the ledger-based identity functionality on cheqd Studio, such as creating DIDs and DID-Linked Resources.

If you need to add CHEQ tokens to your cheqd Studio cheqd_account, there are a few steps you need to follow:

Once you have successfully created an account and have topped up your CHEQ tokens, you are ready to get started!

Step 3: Continue using cheqd

Get started with our tutorials for cheqd Studio functionality.

API keys are unique data strings used to authenticate a user and enable access to privileged operations on cheqd Studio APIs. All cheqd Studio APIs use API keys as the mechanism to authenticate client requests. Your API key should be kept confidential and secure at all times.

• Authentication is required for all API requests; without it, the requests will fail.

• All API requests must be made over HTTPS.

Step 1: Sign into cheqd Studio

Follow the tutorial here to get started with your cheqd Studio account.

Step 2: Generate API key

Navigate to the "Developers" tab on cheqd Studio and select "Create an API Key". You are able to choose the expiry date of the API key, and it will automatically be set to expire 1 year from the current date.

Step 3: Use your API key to authenticate with cheqd Studio APIs

Navigate to the "APIs" tab and copy/paste your API key into the API key box towards the top of your page. This will enable you to authenticate with the cheqd Studio APIs, allowing users to use cheqd Studio APIs within their existing Billing Plan and usage limits.

Step 4: Start using cheqd

Get started with our tutorials for cheqd Studio functionality.

A Decentralized Identifier "DID" is a globally unique identifier that does not require a centralized registration authority because it is registered with distributed ledger technology or other form of decentralized network.

What options do I have for creating DIDs on cheqd?

There are many different ways to create DIDs on cheqd, with options for easy integration (e.g. cheqd Studio) and more bespoke integrations (e.g. Credo and Veramo). Below are a list of options for creating cheqd DIDs.

Get started with cheqd Studio

The easiest way to start creating DIDs is with our product cheqd Studio, allowing users to build and create did:cheqd DIDs using REST APIs.

Read up on our DID Method

DIDs created using cheqd Studio use the did:cheqd DID Method. This is fully defined below, as well as the associated ledger-write fees:

Run as standalone application using Docker Compose

This standalone service uses an in-memory database with no persistence, and therefore is recommended only if you're managing key/secret storage separately.

Run with external Key Management System (KMS) and/or authentication service using Docker Compose

Construct the postgres URL and configure the env variables mentioned above.

Configure PostgreSQL database

1. POSTGRES_USER: Username for Postgres database

2. POSTGRES_PASSWORD: Password for Postgres database

3. POSTGRES_MULTIPLE_DATABASES: Database names for multiple databases in the same cluster, e.g.: "app,logto". This sets up multiple databases in the same cluster, which can be used independently for External Veramo KMS or LogTo service.

Then, make the Postgres initialisation scripts executable:

Start LogTo service

Then, run the LogTo service to configure the LogTo application API resources, applications, sign-in experiences, roles etc using Docker Compose:

Start credential-service app

Then, start the service using Docker Compose:

Running app or LogTo migrations

When upgrading either the external Veramo KMS or LogTo, you might need to run migrations for the underlying databases.

For example, to run cheqd Studio app migrations on an existing Postgres database (for external Veramo KMS):

Or to run LogTo migrations on an existing Postgres database:

Build using Docker

A user is able to input a DID (string) as a request format and resolve the DID to fetch the associated DID Document, DID Resolution Metadata and DID Document metadata.

To create a cheqd DID (did:cheqd) and associated DID Document there are two ways of building the payload for the request:

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 and associated DID Document

Using the /did/create API, users have two options for creating a did:cheqd DID and associated DID Document on-ledger:

1. Filling out a simple form using the application/x-www-url-form-encoded option within an API client of your choice.

2. Compiling a DID Document body yourself using the application/json option within an API client of your choice.

Option 1. Choose from a few variables and we will compile the DID for you

This is the easiest way to create DIDs on cheqd and is recommended for users who are not overly familiar with compiling DID Documents.

Using the application/x-www-url-form-encoded option, users are able to choose between the following variables to compile your DID:

{
  "service": [
    {
      "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1",
      "type": "LinkedDomains",
      "serviceEndpoint": [
        "https://example.com"
      ]
    }
  ]
}

From this request, the Credential Service will automatically create and publish a DID and associated DID Document to the ledger and return it as a response.

Option 2. Publish a DID Document body yourself

Instead of generating a DID Document using simple parameters, you can create a fully formatted DID Document yourself. Before, submitting a manually created DID, you will need to have created a set of identity keys to input the key material into the DID document.

Step 1: Create a new keypair

Use the /key/create API to generate a new keypair within the Credential Service key management store. Copy the "publicKeyHex".

Step 2: Utilise the DID Document template helper

To simplify this process of formatting a DID Document using your own keys, we've created a Helper Tool in our DID Registrar here. Simply paste in your publicKeyHex and choose the variables to compile your DID Document template.

Step 3: Paste the response

Within the /did/create JSON payload, paste the response of your DID Document template, with your own signing keys.

Request format:

{
  "didDocument": {
    "id": "did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63",
    "controller": [
      "did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63"
    ],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63#key-1",
        "type": "JsonWebKey2020",
        "controller": "did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63",
        "publicKeyJwk": {
          "crv": "Ed25519",
          "kty": "OKP",
          "x": "BFSLOxwMJgpmWRtTUuo0JAvz6VXGp4WDDcN0dFfCQKo"
        }
      }
    ],
    "authentication": [
      "did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63#key-1"
    ]
  }
}

Step 3: Hit execute on the API

Hit execute on the API below to create your did:cheqd DID and associated DID Document.

List DIDs associated with your account

After creating a DID or multiple DIDs, users can list all the created DIDs associated with their account. Using the /did/list API.

Alternatives

Below are a list of alternatives for creating cheqd DIDs.

Issuers may want to create identity keypairs for multiple reasons, such as for signing payloads or for creating did:key DIDs.

There is also an option to fetch an identity keypair by inputting a Key ID (kid) as a request format.

Creating a Subject DID

cheqd Studio currently supports two types of subject DIDs:

• did:key

• did:vda

With the former, you can follow the did:key specification to create a subject DID based on a generated keypair.

With the latter, you can setup your did:vda subject DID on your Verida wallet. Using cheqd Studio, you will be able to send credentials to your Verida wallet and use it to store and securely back them up.

Users are able to update DID Documents for various reasons, such as to include a new section or to rotate the Verification Method keys within the DID Document.

With the /did/update API, users are able to input either:

1. The section of the DID Document they would like to update; or

2. The full updated DID Document body.

Users are also able to deactivate DID Documents to prevent further updates and to provide client applications the relevant information that the DID Document is no longer actively used.

A /did/deactivate request must be signed by all of the Verification Method keys listed in the DID Document.

A Verifiable Presentation is a collection of multiple Verifiable Credentials that are being presented by a holder to a verifier. In addition to checking whether the Credentials are untampered, Verifiable Presentation verification also checks that the holder subject DID is valid.

Step 1: Obtain Presentation to Verify

To verify a Credential, you can either pass the full VP-JWT string or a JSON object. These can be either obtained from a Verifiable Presentation presented to the user.

Step 2: Configure Verification Parameters

The user is able to set verification parameters to filter whether they want to verify certain aspects of a Presentation, including:

Step 3: Execute the API

Use the API below to verify a Presentation

Using the /credential/create API, it is possible to issue Verifiable Credentials, signed by a cheqd DID, in a few clicks or lines of code.

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 an Issuer DID

Before you can issue a Verifiable Credential, you need to create an Issuer DID which is used to sign the Credential payload. Use the API in the page below to create an Issuer DID:

(Optional) Step 3: Create a Subject DID

Again, before you issue a Verifiable Credential, you need to know to whom you are issuing it. If you need to create a Subject DID, you can take a look at the page here:

Step 4: Compile your Credential body

Within the JSON object of the API request, you will need to input the issuer and subject information, as well as the attributes which you want to issue in the Credential. You may also want to add additional fields such as a credentialSchema.

Users have two options for compiling the Credential bodies and issuing Verifiable Credentials:

1. Filling out a simple form using the application/x-www-url-form-encoded option within an API client of your choice.

2. Compiling a Credential body yourself using the application/json option within an API client of your choice.

Option 1. Choose from a few variables and we will compile the Credential body for you

This is the easiest way to issue Credentials and is recommended for users who are not overly familiar with compiling JSON objects.

Using the application/x-www-url-form-encoded option, users are able to choose between the following variables and options to issue Verifiable Credentials:

Additional options for specifying credentialStatus bitstring index

Below are a set of examples of alternative input parameters for users to specify the bitstring index of the issued Credential. The bitstring index is where exactly the issued credential will map to within the Status List. This should be noted and stored by the issuer to keep a record of which issued credentials are active, revoked or suspended:

Option 2. Publish a JSON payload yourself

Instead of using simple form variables, you can issue a Verifiable Credential using a JSON payload with the application/json option.

Request format

Below is an example of the request format for issuing a Verifiable Credential using a custom JSON payload, including some of the possible parameters:

Step 5: Issue a Credential using the API below

Execute the API below to issue a Verifiable Credential, signed by your issuer DID.

Alternatives

Below are a list of alternatives for using Credentials with cheqd support. Each offers a different set of protocols and underlying technical capabilities.

t

Once you have issued your credential and have a JWT as part of the credential proof, you can use the /credential/verify API to check that the JWT has not been tampered.

Step 1: Obtain Credential to Verify

Step 2: Configure Verification Parameters

The user is able to set verification parameters to filter whether they want to verify certain aspects of a Credential, including:

Step 3: Pass the Credential to the API

Simply paste the JWT or the full credential body into the request field of the /credential/verify API, and the API will give you a response including the following verification policies:

1. Whether the Credential has been tampered

2. Whether the Credential has a valid issuance date

3. Whether the Credential has expired

4. Whether the Credential Status is valid

Using cheqd's innovative DID-Linked Resource module, cheqd is able to support decentralized and scalable Verifiable Credential revocation and suspension. Using this API, the user is able to choose whether they would like to publish the revocation status to the cheqd ledger or elsewhere.

Step 1: Locate the Credential Body or JWT to be revoked

It is best practice for issuers to keep a record of the Credentials they have issued, including the "statusListIndex" of the Credentials. From this record system, issuers should be able to fetch either the full Credential Body or the JWT proof of the Credential they want to revoke.

Step 2: Decide whether to publish update to the ledger

When revoking a Credential, issuers can decide whether they want to publish an updated Status List on-ledger, with the revoked credential index updated in the bitstring. The parameter below can be changed to reflect this:

Step 3: Paste the Credential Body or JWT into the API

Paste the Credential Body or JWT into the API below and execute the API to revoke the Credential.

Verifiable Credentials are a tamper-evident data format for asserting a set of claims about a subject. You can issue and verify Verifiable Credentials and Presentations without building complex integrations, using our simple cheqd Studio APIs.

What options do I have for issuing credentials anchored on cheqd?

There are many different ways to issue verifiable credentials signed by DIDs anchored on cheqd, with options for easy integration (e.g. cheqd Studio) and more bespoke integrations (e.g. Credo and Veramo). Below are a list of options for issuing credentials with cheqd underneath:

Partner SaaS products

You can use SaaS products from our partners to create best-in-class credential ecosystems, built on cheqd

Get started with cheqd Studio

Supported Credential types

cheqd supports all four major digital Credential types via its selection of SDKs and APIs. Below you can learn about these Credential formats:

Credential Coverage

Depending on what type of credentials you want to use, choose the SDK that suits your tech stack:

Users are also able to suspend Verifiable Credentials. The difference between revocation and suspension is that suspended Credentials may be unsuspended at a future date; whereas, revoked credentials are permanently revoked.

Step 1: Locate the Credential Body or JWT to be suspended

It is best practice for issuers to keep a record of the Credentials they have issued, including the "statusListIndex" of the Credentials. From this record system, issuers should be able to fetch either the full Credential Body or the JWT proof of the Credential they want to suspend.

Step 2: Decide whether to publish update to the ledger

When suspending a Credential, issuers can decide whether they want to publish an updated Status List on-ledger, with the suspended credential index updated in the bitstring. The parameter below can be changed to reflect this:

Step 3: Paste the Credential Body or JWT into the API

Paste the Credential Body or JWT into the API below and execute the API to suspend the Credential.

Unsuspend (reinstate) Verifiable Credentials

If a Credential has been suspended, and an Issuer wants to unsuspend the Credential to make it once again valid, the Issuer can reinstate a suspended Credential.

Step 1: Locate the Credential Body or JWT to be unsuspended

It is best practice for issuers to keep a record of the Credentials they have issued, including the "statusListIndex" of the Credentials. From this record system, issuers should be able to fetch either the full Credential Body or the JWT proof of the Credential they want to unsuspend.

Step 2: Decide whether to publish update to the ledger

When unsuspending or reinstating a Credential, issuers can decide whether they want to publish an updated Status List on-ledger, with the unsuspended credential index updated in the bitstring. The parameter below can be changed to reflect this:

Step 3: Paste the Credential Body or JWT into the API

Paste the Credential Body or JWT into the API below and execute the API to unsuspend the Credential.

Build your knowledge about how cheqd's Credential Payment model works, including setting Access Control Conditions, and privacy-preserving payment flows.

Learn about Credential Payments

Get started

Using cheqd Studio, you can get started setting up your encrypted Status Lists with Access Control Conditions below:

t

Issuers are able to add encrypted Status Lists to the body of the Credential if they have previously created an Encrypted Status List on-ledger.

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 an Issuer DID

Before you can create an encrypted Status List for charging for Credentials, 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 an Encrypted Status List

Follow the tutorial here to create an encrypted Status List with a set of Payment Conditions to unlock:

Step 4: Specify the encrypted Status List within Credential body

Follow the instructions within the /credential/create API below to format and issue a Verifiable Credential.

cheqd Studio supports payments for verifying Credential Status. This is an innovative feature that is also commonly known as cheqd's Payment Rails. Using the API in this tutorial, there are multiple ways for a Verifier to pay an Issuer to unlock and verify a Credential's status.

Step 1: Set up an account

A Verifier will need a cheqd Studio account to take advantage of the /credential-status/check API and easily use cheqd's Credential Payments. Make sure you are set up and are logged in, using our guide below:

Step 2: Set parameters for check

Using the /credential-status/check API, users have two options for checking whether a particular Credential index is revoked or suspended:

1. Filling out a simple form using the application/x-www-url-form-encoded option on the Swagger UI.

2. Compiling the JSON transaction yourself using the application/json option on the Swagger UI.

This is the easiest way to check whether a particular credential index is revoked or suspended.

Using the application/x-www-url-form-encoded option on the Swagger UI, users are able to choose between the following variables to compile your DID:

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

employmentCredentialRevocationList

10

Option 1: Automatically paying an Issuer to unlock a Credential Status

To automatically make a payment to an Issuer in order to verify an encrypted Status List, there is an additional variable:

If there is sufficient CHEQ in the account of the Verifier, this will automatically make a payment to the Issuer and meet the Access Control Conditions.

Step 3: Hit the API

In the same action, the Credential Service will perform a verification check on the Credential Status and pay the issuer the fee specified in the Payment Conditions.

Response format

The response format below will indicate clearly whether the check is successful and whether the Credential index in question is revoked / suspended or not.

{
  "checked": true,
  "revoked": false
}

Option 2: Manually Paying an Issuer to unlock a Credential Status

If a Verifier does not want to automatically pay the Issuer using the API, they can choose to make a manual payment to unlock the Credential Status information to build a higher level of trust within the Credential presented to them.

Step 1: Locating Issuers' payment address and conditions

If a Verifier wants to unlock access to the Resource, to gain access to additional information about a Credential presented to them, such as the Credential Status, firstly, the Verifier will be presented Credential, including a link to the Status List within the "credentialStatus" section of the Credential body.

Through following the link in"credentialStatus" section of the Credential body. the The Verifier will be directed to an on-ledger Resource, identifiable through a DID URL, for example:

This on-ledger Resource will contain:

• An encrypted potion of the Resource, such as a Status List bitstring. identified by the "encodedList" property.

• Unencrypted metadata about the Resource, including the issuers' payment address "feePayerAddress" and and the Payment Conditions, "feePaymentAmount" and "intervalInSeconds".

This gives the verifier requisite information they need in order to pay the Issuer to unlock the Credential Status. You can learn more about Access Control Conditions below.

Step 2: Pay the Issuer

Using one of cheqd's supported wallets, Verifiers can make a payment of the amount specified in the "feePaymentAmount" to the "feePayerAddress".

This payment should be made in CHEQ.

Step 3: Hit the API

cheqd Studio will perform a verification check on the Credential Status and pay the issuer the fee specified in the Payment Conditions.

Response format

The response format below will indicate clearly whether the check is successful and whether the Credential index in question is revoked / suspended or not.

{
  "checked": true,
  "revoked": false
}

Alternatively, if Verifiers have made the payment manually they can also use the /credential/verify API in the tutorial below:

Access Control Conditions

The Access Control Conditions outlined in this section establish a secure and structured framework for unlocking encrypted Status Lists and other DID-Linked Resource.

By employing a combination of Decentralised Identifiers (DIDs), DID-Linked Resources, encryption, and timed payment mechanisms, these access control conditions safeguard the integrity of the Resource, promote transparency, and control access to its data.

Request format: Payment conditions

For Credential Payments, the predominant Access Control Condition is a payment made from the Verifier of a Credential back to the Issuer.

The payment conditions outlined in the code snippet below define the payment requirements that must be met to access and interact with an encrypted Resource. These are written into a payload.json file when a create Status List transaction is made to the ledger (see section below on creating an encrypted Status List).

These conditions are established to ensure that authorized entities or users contribute a specified fee before gaining access to the Resource.

    "paymentConditions": [
        {
            "type": "timelockPayment",
            "feePaymentAddress": "cheqd1xl5wccz667lk06ahama26pdqvrkz5aws6m0ztp",
            "feePaymentAmount": "147603000000000ncheq",
            "intervalInSeconds": 3153600000
        }
    ],

The parameters within the payment conditions are defined as follows:

By including these payment conditions in the Status List Payload, the ledger enforces a financial gate from verifiers seeking access. Additionally, the timelock mechanism adds a layer of time-based verification to the payment process. With the timelock, the payment can only be made in a specific time-interval from the latest block-time on the cheqd network. This ensures that historical payments cannot be used to meet the access control conditions, and fresh payments need to be made to access the Resource, helping to maintain the integrity of the payment and access process.

Response format: Access Control Conditions

If a Payment Condition is set upon creation of a Status List or other Resource, this will populate an Access Control Condition which is broadcasted across series of nodes to monitor whether the conditions have been met. The Access Control Condition uses query language to directly fetch information from the cheqd ledger, and is fully derived from the inputs made into the Payment Condition.

{
    "unifiedAccessControlCondition": {
        "conditionType": "cosmos",
        "path": "/cosmos/tx/v1beta1/txs?events=transfer.recipient='cheqd1xl5wccz667lk06ahama26pdqvrkz5aws6m0ztp'&events=transfer.amount='147603000000000ncheq'&order_by=2&pagination.limit=1",
        "chain": "cheqdMainnet",
        "method": "timelock",
        "parameters": ["latest"],
        "returnValueTest": {
            "key": "$.tx_responses.*.timestamp",
            "comparator": "<=",
            "value": "3153600000"
        }
    },
    "returnTxResponse": true
}

Each of these conditions are defined as follows:

Once an Access Control Condition has been set, the decryption keys are sharded between an array of nodes to prevent any single node or few malicious nodes from decrypting the data. This comprehensive setup ensures secure and controlled access to the specified resource based on specified criteria and events from the cheqd blockchain.

Get started

Using cheqd Studio, you can get started setting up your encrypted Status Lists with Access Control Conditions below:

The /credential-status/update/encrypted API enables users to update the indices of a Status List or rotate the encryption keys. This may be useful for revoking Credentials in bulk, rather than submitting individual /credential/revoke requests.

When a new encrypted Status List resource is published, this will also encrypt the latest version with a new set of encryption keys. This may therefore be used to rotate encryption keys, even if the listed indices are kept the same.

To create an encrypted Verifiable Credential Status List v2021 with a set of Access Control Conditions, an Issuer will need to follow the steps below:

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 an Issuer DID

Before you can create an encrypted Status List for charging for Credentials, 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: Select the encrypted Status List API

When creating a Status List, a user will have the following options:

For the purpose of this tutorial, we will assume the user is creating an encrypted Status List. For unencrypted Status Lists, follow the tutorial here.

Step 4: Create encrypted Status List

Using the /credential-status/create/encrypted API, users have two options for creating an encrypted Status List on-ledger:

1. Filling out a simple form using the application/x-www-url-form-encoded option on the Swagger UI.

2. Compiling a Status List payload yourself using the application/json option on the Swagger UI.

Option 1. Choose from a few variables and we will compile the Status List for you

This is the easiest way to create encrypted Status Lists on cheqd and is recommended for users who are not overly familiar with compiling JSON objects.

Using the application/x-www-url-form-encoded option on the Swagger UI, users are able to choose between the following variables and options to create an encrypted Status List on-ledger:

did:cheqd:testnet:0ff9df5d-653b-4f77-a66c-0035abc34d63

employmentCredentialRevocationList

cheqd1qs0nhyk868c246defezhz5eymlt0dmajna2csg

100

10

140000

1.0

https://www.foo.com

From this request, cheqd Studio will automatically create and publish an encrypted Status List to the ledger with set Payment Conditions required to be met to unlock.

Option 2. Publish a JSON payload yourself

Instead of using simple form variables, you can create an encrypted Status List using a JSON payload yourself using the application/json option on the Swagger UI.

Request format

An example of the JSON payload needed to be submitted is below:

{
  "did": "did:cheqd:testnet:7c2b990c-3d05-4ebf-91af-f4f4d0091d2e",
  "statusListName": "cheqd-employee-credentials-encrypted",
  "paymentConditions": [
    {
      "feePaymentAddress": "cheqd1qs0nhyk868c246defezhz5eymlt0dmajna2csg",
      "feePaymentAmount": 20,
      "feePaymentWindow": 10
    }
  ]
}

The table below expands on some of the required parameters:

Step 5: Hit the API

Once the Issuer has populated the requisite information for the encrypted Status List request, they can use the API below to submit it to the ledger.

Encrypted Status List Response format

The following code snippet shows an example of an encrypted Status List response format, which will be published to the ledger:

{
  "created": true,
  "resource": {
    "StatusList2021": {
      "encodedList": "496fdfbeb745b4db03fcdb40566f9c4c4a1c0f184b31255e641b6e7bdfb9b6946c12be87ca3763be0393c00b67ac1e8737c106b32f46ef59c765754415b5e8cc7c65fccaa3374620430ea476301a5e0dd63340e7a27a68bc627518471f22e4a2",
      "type": "StatusList2021Revocation",
      "validFrom": "2023-06-26T11:45:19.349Z"
    },
    "metadata": {
      "type": "StatusList2021Revocation",
      "encoding": "base64url",
      "encrypted": true,
      "encryptedSymmetricKey": "b11182dc524b8181f9a6aef4c4ad0a1c14e40033b9112dffd8d1bcf6cc3b85abc07ded2205ee94068a99f4202502cb0855f322583fa6ce1534d3a05bf36891766ea2c5f90a982b3040680762977d404d758a2370224a239c8279aa7d21e980931c42055b17ca4c7dbffa4782480a8b6279cf989b2f166d5fdb4b2c1b5a63927200000000000000203018dcaba26df45a415bb599218b27ca853a70289d7a3ed3ed0e3730452e8f8d9af91b6e71312565d2c069341f6660ab",
      "paymentConditions": [
        {
          "feePaymentAddress": "cheqd1qs0nhyk868c246defezhz5eymlt0dmajna2csg",
          "feePaymentAmount": "20000000000ncheq",
          "intervalInSeconds": 600,
          "type": "timelockPayment"
        }
      ]
    },
    "resourceMetadata": {
      "resourceURI": "did:cheqd:testnet:7c2b990c-3d05-4ebf-91af-f4f4d0091d2e/resources/5945233a-a4b5-422b-b893-eaed5cedd2dc",
      "resourceCollectionId": "7c2b990c-3d05-4ebf-91af-f4f4d0091d2e",
      "resourceId": "5945233a-a4b5-422b-b893-eaed5cedd2dc",
      "resourceName": "cheqd-revocation-encrypted-1",
      "resourceType": "StatusList2021Revocation",
      "mediaType": "application/json",
      "resourceVersion": "2023-06-26T11:45:19.349Z",
      "created": "2023-06-26T11:45:20Z",
      "checksum": "909e22e371a41afbb96c330a97752cf7c8856088f1f937f87decbef06cbe9ca2",
      "previousVersionId": null,
      "nextVersionId": null
    },
    "symmetricKey": "dfe204ee95ae74ea5d74b94c3d8ff782273905b07fbc9f8c3d961c3b43849f18"
  }
}

Trust Registries enable a Relying Party to determine the authenticity and authorization of a legal entity within a digital credential ecosystem. Trust Registries are crucial to establish for production environments, because they allow relying parties to make informed decisions on whether to trust the credentials they receive.

cheqd has pioneered a industry-leading trust registry solution, allowing users to create hierarchical chains of trust, with each trust registry entry being DID-Resolvable.

Learn about cheqd Trust Registries

cheqd supports multiple Trust Registry Data Models, using its flexible DID and DID-Linked Resource architecture. Users should familiarise themselves with each Trust Registry approach before getting started with our APIs.

Learn about a data model below:

Get started

Start building with our cheqd Studio APIs and configure a trust registry for your digital credential ecosystem:

Extensions

cheqd's Trust Registry model can work in conjunction with the Eclipse Foundation's TRAIN implementation for establishing secure Roots of Trust and Trust Registry policy resolution.

Introduction​

Verifiable Credentials (VCs) are, in most cases, issued by legal entities. The purpose of Verifiable Credentials is to provide the Relying Party that receives the credentials a Level of Assurance (LoA) that the attributes and claims within the credential are legitimate. However, it is not currently easy to determine whether a legal entity issuing a credential is in fact the entity they claim to be, and not, a fraudulent misrepresentation of that legal entity. This is the challenge that Trust Infrastructure and Trust Registries are positioned to solve.

At present, legal entities that issue credentials have no mechanism to establish that they are trustworthy; thus, Relying Parties may not recognise the DIDs signing the Verifiable Credentials they receive. To fully establish trust, Relying Parties need to know who issued the VCs, whether the issuer is recognised as trusted within a particular governance framework, and who accredited the issuer for the purpose of issuing the credential.

To solve this industry-wide challenge, cheqd introduces a Verifiable Trust Infrastructure, that directly complements the model created by EBSI. Within cheqd's Trust Infrastructure, users can create hierarchical chains of trust "Trust Chains" that together encapsulate a "Trust Registry" for a given ecosystem.

The Trust Infrastructure Model also includes permissions and policies set via "Verifiable Accreditations" and an overall "Governance Framework". Herein, permissions govern the scope of , while policies are used to define who made the accreditation; which Trust Framework is followed; and, the legal basis of the credential.

cheqd Trust Infrastructure users make the whole Verifiable Trust Model publicly available by registering it as a collection of DID-Linked Resources on cheqd. cheqd's Trust Infrastructure therefore enables verifiers to automatically resolve and establish trust in hierarchies of trust without needing to know each organisation directly, using industry-standard resolution mechanisms defined in the W3C DID-Core and the DID Resolution Spec.

Glossary​

There are many terms used within this guide, and as such, familiarise yourself or refer back to the concepts within the glossary below:

Establishing a Trust Hierarchy

cheqd's Trust Registry model is predicated on the notion of a trust hierarchy, which is conceptually very similar to traditional Public Key Infrastructure (PKI). Specifically, the model relies on a Root of Trust from which trusted relationships can be established.

In our model, each organisation in the trust hierarchy is able to issue Verifiable Accreditations to other entities, conveying a set of permissions or scopes that determine what the recipient entity is permitted to do.

The following diagram show how a Root TAO accredits two TAOs lower in the hierarchy:

where:

• Root of Trust (rTAO) DID:

  • Controls Verifiable Accreditations (VAs) issued from rTAO to TAOs.

• Accredited Org (TAO) DID:

  • Controls Verifiable Accreditations (VAs) issued from TAOs to Trusted Issuers.

• Trusted Issuer DID:

  • Issues Verifiable Credentials with Issuance Policies

• Verifiable Credentials

  • Issued including the Issuance Policies in the TermsOfUse section of the data model.

  • Issued to Digital Identity Wallet of user or organisation, which can be later verified up the entire trust chain.

Trust Infrastructure Roles and their Permissions

As shown in the diagram above, legal entities can play the following roles:

• Root Trusted Accreditation Organisation (Root TAO)

• Trusted Accreditation Organisation (TAO)

• Trusted Issuer (TI)

A Trust Chain should contain all three roles, even if one single DID would represent all three roles. The roles must be RTAO, TAO, and TI, where only TI may issue domain-specific Verifiable Credentials.

Root Trusted Accreditation Organisation (RTAO)

The Root TAO is the owner of a Trust Chain, responsible for the governance of the whole Trust Chain. Root TAOs may:

• accredit itself to govern or issue domain-specific Verifiable Credentials

• accredit TAOs to govern a segment of the Trust Chain

• accredit a Trusted Issuer to issue domain-specific Verifiable Credentials

• revoke an accreditation from a legal entity that is participating in the Trust Chain

The RTAO permission is defined by VerifiableAuthorisationForTrustChain, and the policies are contained in termsOfUse as TrustFrameworkPolicy.

Trusted Accreditation Organisation (TAO)​

A TAO governs an accredited segment on behalf of the RTAO. It may:

• accredit itself to issue domain-specific Verifiable Credentials

• accredit another TAO to govern a segment of the Trust Chain

• accredit a Trusted Issuer to issue domain-specific Verifiable Credentials

• revoke accreditation from a legal entity that was accredited by the TAO

The TAO permission is defined by VerifiableAccreditationToAccredit, and the policies are contained in termsOfUse as AccreditationPolicy.

Trusted Issuer (TI)​

A Trusted Issuer represents the Issuer in a Trust Chain. It may issue domain-specific Verifiable Credential types defined by the received accreditation.

The TI permission is defined by VerifiableAccreditationToAttest, and the policies are contained in termsOfUse as AccreditationPolicy. When the Trusted Issuer is using their accreditation to issue a domain-specific VC, the issued domain VC must contain a termsOfUse property with AttestationPolicy type, which links to the Trusted Issuer's accreditation and into Root TAO's accreditation, where both are located in TIR.

Policies Overview​

The Governance Framework Policy is a document, written by a Governance Authority, that defines requirements that must be met for the Trust Ecosystem. These requirements may include security, legal, operational, or functional requirements and may relate to regulation, directives, national policy, or similar documents.

All Trust Model policies are located in the termsOfUse property of the corresponding Accreditation or credential that contains the permissions related to the policy.

Trust Types​

Accreditations​

Accreditations are certifications of being qualified to accredit or attest. Accreditations are attribute-driven and are always restricted to domain-specific credential types. These restrictions cannot be extended. For example, if a legal entity is accredited to accredit Issuers of diploma VCs, they may only pass this or a subset downstream of the hierarchy. Depending on the accreditation, the accredited legal entity may govern (accredit) or issue (attest), but always within the Trust Model and the accredited boundaries.

Each Verifiable Accreditation is also associated with an AccreditationPolicy in the termsOfUse section of the credential. This Policy links to the parent or root accreditation to enable verifiers to traverse the trust registry.

Credentials​

All Verifiable Credentials are attestations of something. Any issuer may issue credentials (default), while accredited Trusted Issuers may issue domain-specific VCs with the accreditation, by attaching the AttestationPolicy into termsOfUse.

End Users (legal entities or natural persons) can accumulate multiple Verifiable Credentials from one or many Trust Models.

Credential Payments brings a significant evolution to the Verifiable Credentials landscape, allowing verifiers to directly pay issuers to unlock Credential Status information. Underneath the hood, we've engineered a robust and secure payment flow that streamlines the end-to-end payment process, with accuracy, speed, and cryptographic integrity.

Get started

Create encrypted Status Lists on-ledger, and pay to unlock the Access Control Conditions in CHEQ, using our cheqd Studio Payments APIs:

Learn more

Build your understanding of How Credential Payments work, including Access Control Conditions and how the model preserves privacy.

Alternatives

Below are a list of alternatives for using Credential Payments.

Trust Registries are referenced within Accreditaiton Policies in the Verifiable Credential body. This enables Relying Parties to traverse the trust chain and verify that the issuer, accrediting entity (TAO) and Root of Trust (rTAO) are all legitimate entities.

Within the body of the Verifiable Credential, issuers will need to configure the termsOfUse section to reference DIDs or DID URLs of trust registry entries, for example:

Users are able to issue Verifiable Accreditations to determine the validity of the accreditation, as well to traverse the trust chain to a root of trust.

Step 1: Issue Accreditation

Make sure you have already created at least one Verifiable Accreditation that you are able to query in the verify API.

Step 2: Use the Verify Accreditation API

As a Trusted Accreditation Organisation (TAO), it is possible to accredit Sub-Trusted Accreditation Organisations (SubTAOs) to issue Verifiable Accreditations or Verifiable Attestations.

The Verifiable Accreditation should include:

Permissions

Root TAOs can set permissions under which TAOs must abide. This creates a level of codified governance for the trust ecosystem.

Whereby:

Policies

The Root TAO can also set polices known as the AccreditationPolicy within the termsOfUse section of the Verifiable Accreditation.

Whereby:

Status Lists are generally sets of indices which can be used to mathematically derive whether an issued Credential has been revoked, suspended or is still valid. Status Lists are crucial for verifier applications to determine whether to accept a credential, presented by a holder.

What options do I have for creating status lists on cheqd?

There are many different ways to create status lists on cheqd, with options for easy integration (e.g. cheqd Studio) and more bespoke integrations (e.g. Credo and Veramo). Below are a list of options for creating cheqd DIDs.

Get started with cheqd Studio

There are two predominant Status List formats supported in cheqd Studio. Please choose a Status List type below to get started.

The /credential-status/update/unencrypted API enables users to update the indices of a Status List. This may be useful for revoking Credentials in bulk, rather than submitting individual /credential/revoke requests.

Users are able to issue Verifiable Accreditations as DID-Linked Resources on-ledger, which may be used to verify whether a particular recipient of an accreditation is accredited to issue a certain type of credential, under the scope of a particular governance framework. This implementation on cheqd builds on the principles of the EBSI Trust Chain model, using DID-Linked Resources to create a more standardised format for storing, retrieving and dereferencing to trust registry entries.

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 Verifiable Accreditation, you need to create a DID which is used to link to one or multiple Verifiable Accreditations on-ledger. Use the API in the page below to create a DID:

Step 3: Choose the type of Accreditation

Verifiable Accreditations are JSON objects that take the form of the Verifiable Credential data model. There are three types of Verifiable Accreditation:

Step 4: Compile the appropriate request format for the API

For each accreditation type, the user will need to use a different request format for the API.

Verifiable Authorisation for Trust Chain

Verifiable Accreditation to Accredit

For a trusted ecosystem, these attestations are required to trace the legitimacy of a credential issuer to a root-of-trust.

Verifiable Accreditation to Attest

For a trusted ecosystem, these attestations are required to trace the legitimacy of a credential issuer to a root-of-trust.

Step 5: Make request to the API

Step 7: Reference the Verifiable Accreditation

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

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

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

Specific version of the Verifiable Accreditation

Here, the "resourceURI" specifies the DID URL of the specific Verifiable Accreditation that was created.

Latest version of the Verifiable Accreditation

In order to reference the latest version of the Verifiable Accreditation, 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=OxfordUniversityAccreditation&resourceType=VerifiableAccreditationToAccredit

Verifiable Accreditation at specific point in time

In order to reference the Verifiable Accreditation 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=OxfordUniversityAccreditation&resourceType=VerifiableAccreditationToAccredit&resourceVersionTime=2023-02-22T06:58:18.61Z

Get started

Understanding Status List v2021

Figure 1: Graphic showing the StatusList2021 bitstring

Where is the StatusList usually published?

The issuer keeps a bitstring list of all Verifiable Credentials it has issued. The Status List is usually published by the issuer in the format of its own Verifiable Credential. This Verifiable Credential is generally hosted publicly on a centralised server or domain to enable third-party read-access.

Where does cheqd store the Status List?

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: Select the unencrypted Status List API

Step 4: Create unencrypted Status List

Using the /credential-status/create/unencrypted API, users have two options for creating an encrypted Status List on-ledger:

1. Filling out a simple form using the application/x-www-url-form-encoded option within an API client of your choice.

2. Compiling a Status List payload yourself using the application/json option within an API client of your choice.

Option 1. Choose from a few variables and we will compile the Status List for you

This is the easiest way to create unencrypted Status Lists on cheqd and is recommended for users who are not overly familiar with compiling JSON objects.

Using the application/x-www-url-form-encoded option, users are able to choose between the following variables and options to create an unencrypted Status List on-ledger:

Option 2. Publish a JSON payload yourself

Instead of using simple form variables, you can create an encrypted Status List using a JSON payload yourself using the application/json option on the Swagger UI.

Request format

An example of the JSON payload needed to be submitted is below:

Step 5: Hit the API

Once the Issuer has populated the requisite information for the unencrypted Status List request, they can use the API below to submit it to the ledger.

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 specification may be found below:

The /credential-status/search API allows users to search for specific entries of a Status List on the cheqd network. For example, if there are multiple Status Lists associated with the same DID, the search functionality allows applications to make requests only to a specified Status List.

Step 1: Set Status List Search Filters

Users are able to filter by:

Step 2: Hit the API

Execute the filters from Step 1 on the API below:

Introduction

cheqd Studio is a set of guides, tutorials and APIs to help users establish an end-to-end trusted ecosystem for digital credentials.

Using REST APIs, customers can build cheqd's trust infrastructure into existing applications. All of cheqd’s existing open-source libraries remain available, and cheqd Studio does not necessitate developers to switch their SSI stack in their entirety, but allows them to build into their existing tooling, for example alongside APIs such as the Universal Resolver.

Get started

Features

Understanding the different modes and client choices

With cheqd Studio, there are multiple ways it can be deployed and hosted to support clients with different requirements.

Option 1: Custodied by cheqd (Custodian Mode)

This mode is the most simple for users, allowing cheqd to custody both Cosmos AND Identity keys in Veramo KMS. This means that manages both ledger-writes and signing identity transactions on behalf of the customer.

To ensure this is highly secure, we have deployed an instance of a Veramo Key Management Store (KMS) which uses a Postgress DB (TypeOrm) to store Cosmos AND identity keys in one encrypted table, so it cannot be read in plaintext. This design allows us to segment different customers' keys securely and efficiently.

User optionality and toggles:

Within Custodian mode, we also enable clients to toggle

Option 2: Self-custodied (Client-managed mode)

Client-managed mode gives the cheqd Studio user the ability to utilise their own identity keys for signing identity transactions, while still allowing cheqd Studio to manage the CHEQ account keys for writing to the cheqd network. This mode is intended to be used for more production environments where the user signs each identity transaction independently, affording a greater level of security and control to the client.

Architecture

Alternatives

Below are a list of alternatives for integrating with cheqd. Each offers a different set of protocols and underlying technical capabilities.

Overview

Contents

📝 Architecture Decision Record for On-ledger Resources

Support for AnonCreds using DID-Linked Resources