Walkthrough for setting up Trust Registries for your AI Agents.
Users are able to build AI Agent Trust Registries using our cheqd Studio APIs. The following steps will enable organisations, governance authorities, auditors and AI Agents to establish permissions, rules and hierarchy between each other.
Step 1: Set up your cheqd Studio account
Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:
The first step for any trust registry is a Root DID, which acts as a trust anchor for the chain of trust below. This DID should be for the highest level of trust in your ecosystem, such as a governance authority, a managing company or an auditor.
For more basic trust registries, the company issuing the AI Agent credentials may also be the Root of Trust with the Root DID.
When you accredit an AI Agent or Organisation that builds AI Agents, you need to do so for a particular purpose. These purposes are defined in schemas, containing the fields that MUST or MAY be present in an accreditation or credential.
We have created some template schemas that we suggest you use within your trust registry!
3.1 Verifiable Attestation
This is a schema for a Verifiable Credential issued to your AI Agent from a Trusted Issuer. The Issuer attests to features of the AI Agent, hence we call it a Verifiable Attestation.
Verifiable Attestation Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Verifiable Attestation",
"description": "The schema defines a generic structure for any Verifiable Credentials according to the VCDM v1.1",
"type": "object",
"properties": {
"@context": {
"description": "Semantic context for the issued credential. First element MUST be https://www.w3.org/2018/credentials/v1",
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"contains": {
"const": "https://www.w3.org/2018/credentials/v1"
},
"minItems": 1,
"uniqueItems": true
},
"id": {
"description": "Globally unique identifier for the issued credential",
"type": "string",
"format": "uri"
},
"type": {
"description": "Full type chain, used to identify the credential base types",
"type": "array",
"items": {
"type": "string"
},
"contains": {
"type": "string",
"const": "VerifiableAttestation"
},
"uniqueItems": true
},
"issuer": {
"description": "Defines a property for expressing the issuer of a Verifiable Credential",
"oneOf": [
{
"description": "DID of the credential issuer",
"type": "string",
"format": "uri"
},
{
"type": "object",
"required": ["id"],
"properties": {
"id": {
"description": "DID of the credential issuer",
"type": "string",
"format": "uri"
}
}
}
]
},
"issuanceDate": {
"description": "Defines the date and time, when the issued credential becomes valid",
"type": "string",
"format": "date-time"
},
"issued": {
"description": "Defines when the issued credential was issued",
"type": "string",
"format": "date-time"
},
"validFrom": {
"description": "Defines the date and time, when the issued credential becomes valid",
"type": "string",
"format": "date-time"
},
"validUntil": {
"description": "Defines the date and time, when the issued credential expires",
"type": "string",
"format": "date-time"
},
"expirationDate": {
"description": "Defines the date and time, when the issued credential expires",
"type": "string",
"format": "date-time"
},
"credentialSubject": {
"description": "Defines information about the subject that is defined by the type chain",
"anyOf": [
{
"$ref": "#/$defs/credentialSubject"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/credentialSubject"
}
}
]
},
"credentialStatus": {
"description": "Defines suspension and/or revocation details for the issued credential. Further redefined by the type extension",
"anyOf": [
{
"$ref": "#/$defs/credentialStatus"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/credentialStatus"
}
}
]
},
"credentialSchema": {
"description": "One or more schemas that validate the Verifiable Credential.",
"anyOf": [
{
"$ref": "#/$defs/credentialSchema"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/credentialSchema"
}
}
]
},
"termsOfUse": {
"description": "Contains the terms under which the issued credential was issued",
"anyOf": [
{
"$ref": "#/$defs/termsOfUse"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/termsOfUse"
}
}
]
},
"evidence": {
"description": "Contains the optional evidence used to issue this credential",
"anyOf": [
{
"$ref": "#/$defs/evidence"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/evidence"
}
}
]
}
},
"required": [
"@context",
"id",
"type",
"issuer",
"credentialSubject"
],
"$defs": {
"credentialSubject": {
"description": "Defines information about the subject that is defined by the type chain",
"type": "object",
"properties": {
"id": {
"description": "Defines the DID of the subject that is described by the issued credential",
"type": "string",
"format": "uri"
}
}
},
"credentialStatus": {
"description": "Defines suspension and/or revocation details for the issued credential. Further redefined by the type extension",
"type": "object",
"properties": {
"id": {
"description": "Exact identity for the credential status",
"type": "string",
"format": "uri"
},
"type": {
"description": "Defines the revocation type extension",
"type": "string"
}
},
"required": ["id", "type"]
},
"credentialSchema": {
"description": "Contains information about the credential schema on which the issued credential is based",
"type": "object",
"properties": {
"id": {
"description": "References the credential schema stored on the Trusted Schemas Registry (TSR) on which the Verifiable Authorisation is based on",
"type": "string",
"format": "uri"
},
"type": {
"description": "Defines credential schema type",
"type": "string"
}
},
"required": ["id", "type"]
},
"termsOfUse": {
"description": "Contains the terms under which the issued credential was issued",
"type": "object",
"properties": {
"id": {
"description": "Contains a URL that points to where more information about this instance of terms of use can be found.",
"type": "string"
},
"type": {
"description": "Defines the type extension",
"type": "string"
}
},
"required": ["type"]
},
"evidence": {
"type": "object",
"properties": {
"id": {
"description": "If present, it SHOULD contain a URL that points to where more information about this instance of evidence can be found.",
"type": "string"
},
"type": {
"anyOf": [
{
"description": "Defines the evidence type extension",
"type": "string"
},
{
"description": "Defines the evidence type extension",
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"required": ["type"]
}
}
}
This schema can be always retrieved from the cheqd ledger at:
3.2 Verifiable Accreditation
This is a schema for a Verifiable Credential between two DIDs, to accredit the DIDs for specific purposes. The accreditedFor section of the Accreditation can be modified with specific schemas for AI Agents.
Verifiable Accreditation Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Verifiable Accreditation",
"description": "Schema of a Verifiable Accreditation",
"type": "object",
"allOf": [
{
"$ref": "https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:b003df6f-ec8e-48dd-9a2b-7011c5cf0a5e?resourceName=VerifiableAttestation&resourceType=JSONSchemaValidator2020"
},
{
"properties": {
"credentialSubject": {
"description": "Defines additional information about the subject that is described by the Verifiable Accreditation",
"type": "object",
"properties": {
"id": {
"description": "Defines a unique identifier of the Verifiable Accreditation",
"type": "string",
"format": "uri"
},
"accreditedFor": {
"description": "Defines a list of claims that define/determine the authorisation of an Issuer to issue certain types of VCs",
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaId": {
"description": "Schema, registered in Trusted Schemas Registry, which the accredited organisation is allowed to issue, as per their accreditation",
"type": "string",
"format": "uri"
},
"types": {
"type": "array",
"items": {
"type": "string"
}
},
"limitJurisdiction": {
"anyOf": [
{
"description": "Defines the jurisdiction for which the accreditation is valid",
"type": "string",
"format": "uri"
},
{
"type": "array",
"description": "Defines the jurisdictions for which the accreditation is valid",
"items": {
"type": "string",
"format": "uri"
}
}
]
}
},
"required": ["schemaId", "types"]
}
}
},
"required": ["id", "accreditedFor"]
},
"credentialStatus": {
"description": "Defines revocation details for the issued credential. Further redefined by type extension",
"type": "object",
"properties": {
"id": {
"description": "Exact identity for the credential status",
"type": "string",
"format": "uri"
},
"type": {
"description": "Defines the revocation status type",
"type": "string",
"const": "EbsiAccreditationEntry"
}
},
"required": ["id", "type"]
}
},
"required": [
"credentialSubject",
"termsOfUse"
]
}
]
}
This schema can be always retrieved from the cheqd ledger at:
We suggest that you use the same schemas that we have already made for Verifiable Accreditations and Attestations, although this is not a requirement
3.3 Custom Schemas
Builders can create custom schemas for their AI Agents, or for the accreditations between different organisations in their ecosystems. This is achieved through editing the accreditedFor section of a Verifiable Attestation above.
For example, the following schema shows how the configuration of an AI Agent can be represented within a schema:
Step 4: Publish your schemas to cheqd as DID-Linked Resources
With the Root DID you created in Step 2, you can create links to your schemas, storing them on-chain in a resolvable format.
You can follow the tutorial here to publish your schemas as DID-Linked Resources. Generally we use the resourceType of JSONSchemaValidator2020 for JSON schemas written to the ledger.
This will store the schemas securely on the cheqd Network, where they can be fetched using DID URLs.
Step 5: Issue a Root Authorisation for the Trust Chain
The Root Authorisation in trust registries on cheqd is called a rootAuthorisationForTrustChain. This authorisation contains informartion about the governance framework the AI Agents will operate in, and signifies to trust registry resolvers that they have reached the intended Root.
Authorisations are issued between two DIDs (which may be the same). As such, if you are managing the entire ecosystem, you may need to create multiple DIDs for different roles in the ecosystem. Otherwise, you need to be aware of the DIDs of the organisations you are seeking to authorise.
Generally, the Root Authorisation also contains the schemas and types of credentials that will be issued below in the trust chain.
Note that it is common for the rootAuthorisationForTrustChain to be self-issued, from the same issuer DID to subject DID, authorising it to carry out other operations.
Request format for Verifiable Authorisation for Trust Chain
{
"issuerDid": "did:cheqd:testnet:b003df6f-ec8e-48dd-9a2b-7011c5cf0a5e", // This is the Root DID for the Trust Chain
"subjectDid": "did:cheqd:testnet:6af412d7-2f04-4e12-a424-e6719db487ad", // This is the DID Authorised at a Root Level and may often be the same DID as the issuer
"schemas": [ // enter the schemas you have created for your trust registry
{
"types": "AIAgentAuthorisation",
"url": "https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:c6630f1e-9248-4af6-b7ac-5bcaf646f213?resourceName=AIAgentAuthorisation&resourceType=JSONSchemaValidator2020"
},
{
"uri": "https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:b003df6f-ec8e-48dd-9a2b-7011c5cf0a5e?resourceName=VerifiableAccreditation&resourceType=JSONSchemaValidator2020",
"types": [
"VerifiableCredential",
"VerifiableAccreditation",
"VerifiableAccreditationToAccredit"
]
},
{
"uri": "https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:b003df6f-ec8e-48dd-9a2b-7011c5cf0a5e?resourceName=VerifiableAttestation&resourceType=JSONSchemaValidator2020",
"types": [
"VerifiableCredential",
"VerifiableAttestation",
"VerifiableAccreditationToAttest"
]
}
],
"format": "jwt",
"accreditationName": "authoriseAccreditationTest",
"trustFramework": "https://learn.cheqd.io/governance/start",
"trustFrameworkId": "cheqd Governance Framework"
}
Response format for Verifiable Authorisation for Trust Chain
The "types" of credential you are authorising for your trust chain
"url"
Yes
A schema or multiple schemas that the recipient is accredited to issue
"format"
Optional
Defaults to "jwt" but may also be "json-ld"
"accreditationName"
Yes
Name of the accreditation which is used for chronological versioning of the accreditation.
"trustFramework"
Yes
A URL that points to an Ecosystem Governance Framework
"trustFrameworkId"
Yes
The name of the Ecosystem Governance Framework
"credentialStatus"
Optional
An object detailing the status information of the Accreditation
You can use the API below to make this transaction, using the parameter 'authorise'.
Step 6: Issue your next Accreditation
Depending on how many layers deep you want your trust registry, you now need to issue an accreditationToAccredit or an accreditationToAttest. In essence, you need to decide whether you want to accredit a subordinate entity to accredit other organisations (creating a deeper trust chain), or accredit a subordinate entity to issue Credentials to your AI Agent.
6.1 Verifiable Accreditation to Accredit
Request format for Verifiable Accreditation to Accredit
A schema or multiple schemas that the recipient is accredited to issue
"types"
Yes
The types of credential the subject is accredited to issue
"format"
Optional
Defaults to "jwt" but may also be "json-ld"
"accreditationName"
Yes
Name of the accreditation which is used for chronological versioning of the accreditation.
"parentAccreditation"
Yes
A URL or DID URL of Accreditation of the Issuer demonstrating capacity to issue this Accreditation.
"rootAuthorisation"
Yes
A URL or DID URL of the root authorization governing the ecosystem
"credentialStatus"
Optional
An object detailing the status information of the Accreditation
For a trusted ecosystem, these attestations are required to trace the legitimacy of a credential issuer to a root-of-trust.
Note that there MUST be an accreditationToAttest for credentials to be issued that reference an accreditation in the next tutorial.
Core Trust Registry Setup Complete!
Great! Now you have set up the core functionality for your trust registry. Next you will want to issue a Verifiable Attestation from the "trusted issuer" in the Trust Registry to an AI Agent:
RefreshService property MUST be one or more refresh services that provides enough information to the recipient's software such that the recipient can refresh the verifiable credential.
Evidence property MUST be one or more evidence schemes providing enough information for a verifier to determine whether the evidence gathered by the issuer meets its confidence requirements for relying on the credential.
