DIDs

DID stands for Decentralized IDentifiers. DIDs are meant to be globally unique identifiers that allow their owner to prove cryptographic control over them. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies.

In Truvera, Decentralized Identifiers (DIDs) are created using the UUID v4 standard. This involves selecting a unique 128-bit identifier, typically represented as a 36-character hexadecimal string, along with an initial public key. Users have the flexibility to add and remove public keys associated with their DID document as needed. Additionally, the system supports various operations such as updating, deactivating, and listing all existing DIDs.

For a detailed example of the DIDs workflow. Please refer here.

Create DID

A DID, a public key, and a controller are required to create a new DID. The controller is both the owner of the public key and a DID. The DID can be created using an auto-generated keypair, and the controller will be the same as the DID unless otherwise specified. The DID and public key have no cryptographic relation.

It is important to have a public key types that is supported by Truvera, the supported type of public key is ed25519.

Create DID

post

https://api-testnet.truvera.iohttps://api.truvera.io

/dids

Creates a new DID on chain with an auto generated keypair, the controller will be the same as the DID unless otherwise specified. More info about Create DID

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

typestring · enumOptionalDefault: cheqdPossible values:

didstring · min: 32Optional

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

controllerstring · min: 32Optional

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

keyTypestring · enumOptional

Type of public key for DID (NOTE: secp256k1, sr25519 are deprecated)

Possible values:

didcommServiceUrlstring · uriOptional

Optional custom DIDComm service endpoint URL. If not provided, a default URL will be generated using the server URL and DID. This is not supported for did:key.

Example: https://api.example.com/messaging/did:cheqd:testnet:abc123/receive

includeDidcommServicebooleanOptional

Whether to include a DIDComm service endpoint in the DID document. Defaults to true. Set to false to create a DID without DIDComm service endpoint.

Default: true

Responses

200

DID will be created on the network.

application/json

400

Invalid params

application/json

401

Unauthorized

application/json

402

Transaction limit reached or upgrade required to proceed

application/json

409

Conflict or duplicate

application/json

post

/dids

HTTPcURLJavaScriptPython

POST /dids HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "type": "cheqd",
  "did": "did:cheqd:testnet:3b68ef6c-1eea-493e-9fd5-6f51e5a87fa9",
  "controller": "did:cheqd:testnet:3b68ef6c-1eea-493e-9fd5-6f51e5a87fa9",
  "keyType": "ed25519"
}

{
  "id": "2432",
  "data": {
    "did": "did:cheqd:testnet:f48d2ace-4947-4cb7-8550-1cef3d63e651",
    "controller": "did:cheqd:testnet:f48d2ace-4947-4cb7-8550-1cef3d63e651"
  }
}

Import DIDs

Import an already existing DID, possibly created in another platform, to take advantage of Truvera's advanced functions like ecosystems and monetized credentials.

Import DIDs

post

https://api-testnet.truvera.iohttps://api.truvera.io

/dids/import

Import DIDs from JSON objects (DIDResolutionResponse or Universal Wallet format). Supports both encrypted and plaintext wallet exports.

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

dataone ofRequired

Import data - can be DIDResolutionResponse JSON-LD document, universal wallet export, or array of either

stringOptional

JSON string containing import data

or

objectOptional

Single DID import object

or

arrayOptional

Array of DID import objects

passwordstring · min: 8Optional

Password for encrypted wallet imports

Responses

200

DIDs imported successfully

application/json

400

Invalid import data or missing required fields

application/json

401

Unauthorized

application/json

402

Payment required

application/json

404

DID not found or cannot be resolved

application/json

post

/dids/import

HTTPcURLJavaScriptPython

POST /dids/import HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 397

{
  "data": {
    "@context": [
      "https://w3id.org/wallet/v1",
      "https://w3id.org/did-resolution/v1"
    ],
    "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    "type": [
      "DIDResolutionResponse"
    ],
    "name": "Imported DID",
    "description": "A DID imported from JSON",
    "didDocument": {
      "@context": [
        "https://www.w3.org/ns/did/v1"
      ],
      "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
      "verificationMethod": []
    }
  }
}

{
  "imported": 1,
  "dids": [
    {
      "did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
      "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
      "keyCount": 1,
      "profile": {
        "name": "Imported DID",
        "description": "A DID imported from JSON"
      }
    }
  ]
}

List DIDs

Return a list of all DIDs that your user account controls as fully resolved DID documents.

List DIDs

get

https://api-testnet.truvera.iohttps://api.truvera.io

/dids

Return a list of all DIDs that your user account controls as fully resolved DID documents. More info about Get DID

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

offsetinteger · int32Optional

How many items to offset by for pagination

Default: 0

limitinteger · int32 · min: 1 · max: 64Optional

How many items to return at one time (max 64)

Default: 64

typestringOptional

The type of DID for filtering

Responses

200

All of a user's DIDs with additional information

application/json

400

Application error

application/json

get

/dids

HTTPcURLJavaScriptPython

GET /dids HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
    "did": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
    "type": "cheqd",
    "controller": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
    "credentialCount": "0",
    "updatedLast": "2024-09-26T12:38:10.871Z",
    "profile": {
      "name": "My Convener",
      "logo": "text",
      "description": "An ecosystem convener"
    },
    "keyId": "did:cheqd:testnet:f48d2ace-4947-4cb7-8550-1cef3d63e651#keys-1",
    "jobId": null,
    "trustRegistries": [
      {
        "id": "0x592a...c99b",
        "name": "Updated Name",
        "logoUrl": "https://logo.com/ecosystemnew"
      }
    ]
  }
]

Return ecosystems that DID participates in

Returns ecosystems that this DID is a participant in

get

https://api-testnet.truvera.iohttps://api.truvera.io

/dids/{did}/ecosystems

Returns ecosystems that this DID is a participant in

Path parameters

didstring · min: 32Required

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

Responses

200

Ecosystems list that the DID participates in

application/json

400

Application error

application/json

404

DID was not found.

application/json

get

/dids/{did}/ecosystems

HTTPcURLJavaScriptPython

GET /dids/{did}/ecosystems HTTP/1.1
Host: api-testnet.truvera.io
Accept: */*

{
  "total": 1,
  "list": [
    {
      "id": "0xe7e0f253c5f05059904109e33fb63b104edddd7e114a8746a5faf07a944d58aa",
      "slug": "truvera-ecosystem-419",
      "convener": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
      "created": "2024-09-26T13:18:51.534Z",
      "name": "Truvera Ecosystem",
      "description": "This is my new awesome ecosystem!",
      "logoUrl": "https://logo.truvera.io/trust-registry",
      "ecosystemUrl": "https://ecosystem.truvera.io",
      "governanceFramework": "This is a markdown document describing my framework",
      "governanceFrameworkVersion": "1.0.0",
      "participantRole": "verifier",
      "participantStatus": "active",
      "participantName": "My Convener",
      "participantLogoUrl": "https://logo.com/participant",
      "participantInfoUrl": "https://participant.truvera.io"
    }
  ]
}

Export DID

Exports the DID document and keys as an encrypted Universal Wallet JSON-LD document

Export DID document and keys

post

https://api-testnet.truvera.iohttps://api.truvera.io

/dids/{did}/export

Exports the DID document and keys as an encrypted Universal Wallet JSON-LD document

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

didstring · min: 32Required

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

Body

application/json

passwordstring · min: 2 · max: 128Optional

Responses

200

An encrypted Universal Wallet document containing the DID and its keypairs

application/json

400

Invalid params

application/json

401

Unauthorized

application/json

404

DID was not found.

application/json

post

/dids/{did}/export

HTTPcURLJavaScriptPython

POST /dids/{did}/export HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "password": "astrongpassword"
}

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/wallet/v1"
  ],
  "id": "did:key:z6LS...Wa19#encrypted-wallet",
  "type": [
    "VerifiableCredential",
    "EncryptedWallet"
  ],
  "issuer": "did:key:z6LS...Wa19",
  "issuanceDate": "2024-09-26T12:08:18.803Z",
  "credentialSubject": {
    "id": "did:key:z6LS...Wa19",
    "encryptedWalletContents": {
      "protected": "eyJlbmMiOiJYQzIwUCJ9",
      "recipients": [
        {
          "encrypted_key": "OHwaAnWZThM_lGP-9g_zBSBhbRjOeFEG4LsvTEA5V-5WW63J--Xw4w",
          "header": {
            "kid": "did:key:z6LS...Wa19#z6LS...Wa19",
            "alg": "ECDH-ES+A256KW",
            "epk": {
              "kty": "OKP",
              "crv": "X25519",
              "x": "4xA5LWWdfhLed5AUvHPsDAYaxhsMdV4UBw1kN0As1Hs"
            },
            "apu": "4xA5LWWdfhLed5AUvHPsDAYaxhsMdV4UBw1kN0As1Hs",
            "apv": "ZGlkOmtleTp6NkxTaFZ0VlJiUlA4REFoZm05ODFyQ244WWhNVFBhZzlWNFNNakN..."
          }
        }
      ],
      "iv": "NyMwyU-0QGnaqRVy0u0_Ilae3ETvcZq_",
      "ciphertext": "8MJvLT..._wYO54",
      "tag": "b-fL728NLEZkqz5SEIMI8Q"
    }
  }
}

Get DID

When a DID is provided in the path, the API will attempt to resolve that DID into a DID document. This document contains the public keys and more information relating to that DID, check the identity foundation did configuration document to learn more.

The API supports resolving many DID methods, some examples are:

• did:cheqd:f48d2ace-4947-4cb7-8550-1cef3d63e651 - resolves through the cheqd blockchain

• did🔑z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd- the public key is embedded in the DID

Get DID

get

https://api-testnet.truvera.iohttps://api.truvera.io

/dids/{did}

Returns the complete information about the provided "did" which is provided via parameters text box. More info about Get DID

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

didstring · min: 32Required

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

Responses

200

The DIDDoc

application/json

400

Application error

application/json

404

DID was not found.

application/json

get

/dids/{did}

HTTPcURLJavaScriptPython

GET /dids/{did} HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
  "authentication": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59#keys-1",
  "assertionMethod": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59#keys-1",
  "publicKey": [
    {
      "id": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59#keys-1",
      "type": "Sr25519VerificationKey2020",
      "controller": "ddid:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
      "publicKeyBase58": "BFHGE7DyTM5HtAKz58pkJN4evS4yRtDMYaxqRYtzT5nj"
    }
  ]
}

Get DID metadata

get

https://api-testnet.truvera.iohttps://api.truvera.io

/dids/{did}/metadata

Returns the metadata for your DID

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

didstring · min: 32Required

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

Responses

200

The DIDDoc

application/json

400

Application error

application/json

404

DID was not found.

application/json

get

/dids/{did}/metadata

HTTPcURLJavaScriptPython

GET /dids/{did}/metadata HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "did:cheqd:testnet:f48d2ace-4947-4cb7-8550-1cef3d63e651",
  "jobId": "0"
}

Delete DID

Deletes a DID and its metadata from the blockchain and our platform. This will also delete the associated keypair from the key management system meaning that you cannot sign messages or credentials with it after this operation. The DID will no longer be able to be resolved. This operation is not reversible.

Delete DID

delete

https://api-testnet.truvera.iohttps://api.truvera.io

/dids/{did}

Deletes a provided DID from the blockchain, further attempts to resolve this DID will fail. More info about Delete DID

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

didstring · min: 32Required

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59

Query parameters

fromBlockchainbooleanOptional

Whether to delete the DID from the blockchain (true) or just from the user's account (false). Defaults to true for backward compatibility.

Default: true

Responses

200

Will remove DID.

application/json

400

Something went wrong with deleting the DID

application/json

401

Unauthorized.

application/json

402

Transaction limit reached or upgrade required to proceed

application/json

404

DID does not exist

application/json

delete

/dids/{did}

HTTPcURLJavaScriptPython

DELETE /dids/{did} HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "2430",
  "data": {
    "status": "pending"
  }
}