Credentials

Credential issuance is the process of creating and signing a verifiable credential using the Truvera API. Verifiable Credentials are cryptographically secure and tamper-proof. They cannot be edited once issued, but they can be revoked and replaced with a new credential.

By default, the Truvera API issues a credential to a holder wallet without storing a copy—only credential metadata is stored. If the holder does not yet have a wallet, we recommend provisioning a cloud wallet for that holder and issuing the credential into it. If that is not appropriate for your use case, you can choose to persist the credential, in which case we will encrypt and store the credential for later retrieval using a password.

The following metadata is stored on each issuance:

• Credential ID property

• Credential size in bytes

• Issuer DID

• Issuance date

Issue credential

Creates and issues a JSON-LD verifiable credential that conforms to the W3C VCDM specification. The type values and subject properties must be represented by a schema URI in the context property. If you do not specify a context property, the API will automatically generate an embedded JSON-LD context based on the properties within your credential. You can read more about JSON-LD and contexts here.

The https://www.w3.org/2018/credentials/v1 context URI is always required and will be supplied by default at all times as mandated by the spec. If you pass a custom context, you must ensure that you define all the required JSON-LD terms. Please also note that the request format here is not the same as an issued verifiable credential. You can issue to multiple subjects per credential by passing an array of objects.

To sign a credential, an issuer must be supplied as either a fully qualified DID string or an object with at least an id property which is a fully qualified DID. (e.g: did:dock:xyz)

The issuer property must be a DID that you control with your Truvera account.

Creating an Example Payload

As mentioned in the development tips, you can create an example payload in Truvera Workspace by:

• Open the browser's dev tools

• Look at the network requests

• Manually issue a credential with the desired schema from the desired issuer profile

• In the section that shows HTTP headers, you can copy the Request URL ("Headers" in Google Chrome)

• In the section that shows the request preview, you can copy the text of the request (in Google Chrome, click on "Preview", then right-click on the top-level element "{,...}" and select "Copy object")

Zero Knowledge Proofs (ZKP)

Truvera credentials support anonymous credentials using Zero Knowledge Proofs and Selective Disclosure by using the BBS2023 signing algorithm when issuing the credential. To enable this functionality, simply set the algorithm field in the request to dockbbs.

Credential distribution

As mentioned above, issued credentials are not stored and so should be issue directly into a holder wallet. Truvera's API has built in credential distribution on issuance, allowing you to send credentials directly to a holder's email and/or Truvera-compatible wallet. You can achieve this by supplying the recipientEmail field and distribute: true in your request. For DID distribution, simply set the credentialSubject.id property to the holder's DID.

In some use cases, you might choose to set the persist value to true and provide a password string which will store the credential contents encrypted on our platform.

Revocation

In order to support revocation the credential must be linked to a revocation registry at the time of issuance. To link the revocation registry to the credential set the status field in the Credential body to the registry.id value.

One time use credentials can be created, but automating the revocation based on tracking the verification of the credential ID and revoking the credential associated with it.

Expiration

An expiration date can be set when issuing a credential making the credential invalid after the assigned time. To check the expiration date for Zero Knowledge Proof credentials (using the dockbbs algorythm) the expiration date needs to be requested in the verification template otherwise due to the nature of zero knowledge proof it will not be disclosed automatically.

Attaching files

At the moment it is not possible to add a file to the credential itself. If a credential has to have a file associated with it, the file will need to be placed in public storage and the link to that location and a hash of the content should be added to the attributes of the credential.

Issue a Credential

post

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

/credentials

Creates and issues a verifiable credential with supplied data. More info about Issue a Credential

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

persistbooleanOptional

Whether to store an encrypted version of this credential with us. Defaults to false, if true you must supply password. When choosing to persist a credential containing Personally Identifiable Information (PII), consider the implications for data storage regulatory compliance.

Default: falseExample: false

passwordstring · min: 4 · max: 32Optional

Password used to encrypt the credential if you choose to store it. The same password must be used to retrieve the credential contents. Truvera does not store this password.

anchorbooleanOptionalDeprecated

Anchor the credential on the blockchain or not

Default: falseExample: false

templatestring · uuidOptional

The credential template UUID, only required for PDF and web rendering customization

recipientDIDstringOptional

The holder's DID for DID distribution, optional. Not required for OpenID flows.

recipientEmailstringOptional

The holder's email for email distribution, optional. Not required for OpenID flows.

algorithmstring · min: 4 · max: 32Optional

Optional. Specifies which signing algorithm to use to sign the issued credential. Defaults to ed25519, for ZKP credendials use dockbbs.

Default: ed25519Example: dockbbs

distributebooleanOptional

Whether to distribute the credential or not based on subject DID or email address. Not required for OpenID flows.

Default: falseExample: false

formatstring · enumOptional

Specifies the output format of the credential, either jsonld or jwt. Defaults to jsonld.

Example: jsonldPossible values:

revocablebooleanOptional

Whether the credential can be revoked or not. If true the revocation registry will be automatically provisioned.

Default: falseExample: true

Responses

200

The request was successful and returns the created Verifiable Credential.

application/json

400

The request was unsuccessful, because of invalid/insufficient credential params.

application/json

401

The request was unsuccessful, either because the authorization token was missing/invalid or you don't own the DID.

application/json

402

Transaction limit reached or upgrade required to proceed.

application/json

404

Resource was not found.

application/json

post

/credentials

HTTPcURLJavaScriptPython

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

{
  "persist": false,
  "password": "",
  "template": "",
  "recipientDID": "",
  "recipientEmail": "",
  "algorithm": "dockbbs",
  "distribute": false,
  "format": "jsonld",
  "credential": {
    "id": "",
    "previousCredentialId": "",
    "rootCredentialId": "",
    "name": "Basic Credential",
    "description": "My first credential",
    "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
    "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
    "type": [
      "BasicCredential"
    ],
    "subject": {
      "id": "did:key:z6MkqBcwvYurNSSqyBkxavv4fkaq2iu3v3YGMbdyfa4bVNxD",
      "name": "A. Holder"
    },
    "issuer": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
    "issuanceDate": "2026-02-08T18:49:41.885Z",
    "expirationDate": "2030-09-20T00:13:59.270Z",
    "status": null
  },
  "revocable": true
}

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.com/123",
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "credentialSubject": {
    "id": "did:sample:subject2",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "issuanceDate": "2020-08-24T14:15:22Z",
  "proof": {
    "type": "Sr25519Signature2020",
    "created": "2022-01-14T19:45:12Z",
    "verificationMethod": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59#keys-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z7zTs4pVjGyj68WwsnJ6bCoK2CnWFBW5xmSBin7LxcgoYfzET4YXAZcTF9qQBTVhfVC5hK4FUWp9XAedq8Tep8J6"
  },
  "issuer": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59"
}

List credentials

When you issue a credential with us, persistent or not, we will store certain metadata about the credential to make it easier for you to reference. You can pull a list of credential metadata using this route. To return the content of a persisted credential, you should use the GET /credentials/{id} route.

List Credentials

get

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

/credentials

Get all credential metadata

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: 100Optional

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

Default: 64

filterstringOptional

Filter by specific Credential ID, Subject Ref, Issuer, Type, Created Date or Issue Date

Responses

200

The request was successful and will return the credential metadata.

application/json

400

Application error

application/json

get

/credentials

HTTPcURLJavaScriptPython

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

[
  {
    "id": "https://creds.truvera.io/521bb7...",
    "issuerKey": "did:key:z6Mk...dsmK",
    "issuerName": "Truvera Issuer",
    "type": "VerifiableCredential",
    "revocationRegistry": "e6d3...59d1",
    "revoked": false,
    "createdAt": "2024-09-20T11:13:03.445Z",
    "expiryDate": "2024-09-20T11:13:03.445Z",
    "expirationDate": "2024-09-20T11:13:03.445Z",
    "issuanceDate": "2024-09-20T11:13:02.648Z",
    "byteSize": 1003,
    "persist": false,
    "index": "1004",
    "subjectRef": "Truvera Ref",
    "whitelabel": null,
    "algorithm": "dockbbs",
    "credential": {
      "@context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
      "id": "text",
      "type": [
        "text"
      ],
      "credentialSubject": {},
      "issuer": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
      "issuanceDate": "2026-02-08T18:49:41.885Z",
      "expirationDate": "2026-02-08T18:49:41.885Z",
      "credentialStatus": {},
      "proof": {
        "type": "Ed25519Signature2018",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "text",
        "created": "2026-02-08T18:49:41.885Z",
        "proofValue": "text"
      }
    }
  }
]

Get credentials metadata and contents

When a credential has been persisted on our systems, you can fetch the credential data by supplying a credential ID and the password used at issuance to encrypt the credential.

Get credential metadata and contents if persistent

get

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

/credentials/{id}

Get credential metadata and contents if persistent

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstring · uri · min: 8Required

Valid URI

Example: https://credentials.truvera.io/1234

Query parameters

passwordstring · min: 4 · max: 64Optional

The encryption password used when issuing/storing the credential

Responses

200

The request was successful and will return the credential metadata and its JSON contents (if password was supplied).

application/json

400

Error retrieving the credential

application/json

404

Credential was not found.

application/json

get

/credentials/{id}

HTTPcURLJavaScriptPython

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

{
  "id": "https://creds.truvera.io/521bb7...",
  "issuerKey": "did:key:z6Mk...dsmK",
  "issuerName": "Truvera Issuer",
  "type": "VerifiableCredential",
  "revocationRegistry": "e6d3...59d1",
  "revoked": false,
  "createdAt": "2024-09-20T11:13:03.445Z",
  "expiryDate": "2024-09-20T11:13:03.445Z",
  "expirationDate": "2024-09-20T11:13:03.445Z",
  "issuanceDate": "2024-09-20T11:13:02.648Z",
  "byteSize": 1003,
  "persist": false,
  "index": "1004",
  "subjectRef": "Truvera Ref",
  "whitelabel": null,
  "algorithm": "dockbbs",
  "credential": {
    "@context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
    "id": "text",
    "type": [
      "text"
    ],
    "credentialSubject": {},
    "issuer": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
    "issuanceDate": "2026-02-08T18:49:41.885Z",
    "expirationDate": "2026-02-08T18:49:41.885Z",
    "credentialStatus": {},
    "proof": {
      "type": "Ed25519Signature2018",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "text",
      "created": "2026-02-08T18:49:41.885Z",
      "proofValue": "text"
    }
  }
}

Create request claims

Creates a request to gather certain claims and then issues the holder a credential after submission. The claims are user provided and type is based on the schema provided. This can be useful to catch a subject's DID without knowing it beforehand, name or other field. It should only be used when you do not already know this data or cannot find it by other means. There is a risk that a user may enter false data - so use it sparingly and not for fields that are important.

Typically, once the request has been created, you would show the holder the QR URL as an image or deep link for them to scan with a wallet and enter claims. After the holder submits the requested information the credential is automatically issued.

Issue a Credential after requesting claims from the user

post

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

/credentials/request-claims

Creates and issues a verifiable credential with supplied data + claims from the user.

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

singleUsebooleanOptionalDefault: true

schemastringOptionalExample: https://docknetwork.github.io/vc-schemas/basic-credential.json

claimsstring[]OptionalExample: name

Responses

200

OpenID issuer and claim request created

application/json

400

The request was unsuccessful, because of invalid/insufficient credential parameters.

application/json

402

Transaction limit reached or upgrade required to proceed

application/json

post

/credentials/request-claims

HTTPcURLJavaScriptPython

POST /credentials/request-claims HTTP/1.1
Host: api-testnet.truvera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 863

{
  "singleUse": true,
  "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
  "claims": [
    "name"
  ],
  "credentialOptions": {
    "persist": false,
    "password": "",
    "template": "",
    "recipientDID": "",
    "recipientEmail": "",
    "algorithm": "dockbbs",
    "distribute": false,
    "format": "jsonld",
    "credential": {
      "id": "",
      "previousCredentialId": "",
      "rootCredentialId": "",
      "name": "Basic Credential",
      "description": "My first credential",
      "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
      "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
      "type": [
        "BasicCredential"
      ],
      "subject": {
        "id": "did:key:z6MkqBcwvYurNSSqyBkxavv4fkaq2iu3v3YGMbdyfa4bVNxD",
        "name": "A. Holder"
      },
      "issuer": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
      "issuanceDate": "2026-02-08T18:49:41.885Z",
      "expirationDate": "2030-09-20T00:13:59.270Z",
      "status": null
    },
    "revocable": true
  }
}

{
  "credentialOptions": {
    "persist": false,
    "password": "",
    "template": "",
    "recipientDID": "",
    "recipientEmail": "",
    "algorithm": "dockbbs",
    "distribute": false,
    "format": "jsonld",
    "credential": {
      "id": "",
      "previousCredentialId": "",
      "rootCredentialId": "",
      "name": "Basic Credential",
      "description": "My first credential",
      "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
      "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
      "type": [
        "BasicCredential"
      ],
      "subject": {
        "id": "did:key:z6MkqBcwvYurNSSqyBkxavv4fkaq2iu3v3YGMbdyfa4bVNxD",
        "name": "A. Holder"
      },
      "issuer": "did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59",
      "issuanceDate": "2026-02-08T18:49:41.885Z",
      "expirationDate": "2030-09-20T00:13:59.270Z",
      "status": null
    },
    "revocable": true
  },
  "authProvider": {
    "url": "https://creds.truvera.io/claims",
    "scope": [
      "openid"
    ],
    "clientId": "eyAic2NoZW1hIjogImh0dHBzOi8vZG9ja25ldHdvcmsuZ2l0aHViLmlvL3ZjLXNjaGVtYXMvYmFzaWMtY3JlZGVudGlhbC5qc29uIiwgImNsYWltcyI6IFsibmFtZSJdIH0=",
    "clientSecret": "gpO2IVK+OALL8W+DcFlIfFhJtNA=",
    "claimsSource": "idToken",
    "requestParameters": {
      "login_hint": "[email protected]",
      "prompt": "login"
    }
  },
  "claimMap": {
    "name": "name"
  },
  "singleUse": false,
  "issuer": "text",
  "protocol": "default"
}

Get request claims

Lists all created request claims that are open (the holders have not submitted the requested information).

List Credentials

get

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

/credentials/request-claims

Get all credential metadata

Authorizations

accessTokenbearerAuthnextAuthrapidAPI

DOCK-API-TOKENstringRequired

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

Responses

200

A paged array of OpenID issuers

application/json

400

Application error

application/json

get

/credentials/request-claims

HTTPcURLJavaScriptPython

GET /credentials/request-claims HTTP/1.1
Host: api-testnet.dock.io
DOCK-API-TOKEN: YOUR_API_KEY
Accept: */*

[
  {
    "credentialOptions": {
      "persist": true,
      "password": "securepass",
      "anchor": false,
      "template": "",
      "recipientEmail": "",
      "algorithm": "dockbbs",
      "distribute": false,
      "format": "jsonld",
      "credential": {
        "id": "",
        "name": "Basic Credential",
        "description": "My first credential",
        "schema": "https://docknetwork.github.io/vc-schemas/basic-credential.json",
        "context": "https://docknetwork.github.io/vc-schemas/basic-credential.json-ld",
        "type": [
          "BasicCredential"
        ],
        "subject": {
          "id": "did:key:123",
          "name": "A. Holder"
        },
        "issuer": "did:dock:xyz",
        "issuanceDate": "2026-02-08T18:49:41.885Z",
        "expirationDate": "2030-09-20T00:13:59.270Z",
        "status": null
      }
    },
    "authProvider": {
      "url": "https://creds.dock.io/claims",
      "scope": [
        "openid"
      ],
      "clientId": "eyAic2NoZW1hIjogImh0dHBzOi8vZG9ja25ldHdvcmsuZ2l0aHViLmlvL3ZjLXNjaGVtYXMvYmFzaWMtY3JlZGVudGlhbC5qc29uIiwgImNsYWltcyI6IFsibmFtZSJdIH0=",
      "clientSecret": "gpO2IVK+OALL8W+DcFlIfFhJtNA=",
      "claimsSource": "idToken",
      "requestParameters": {
        "login_hint": "[email protected]",
        "prompt": "login"
      }
    },
    "claimMap": {
      "name": "name"
    },
    "singleUse": false,
    "issuer": "text",
    "protocol": "default"
  }
]

Delete credential

A credential can have its metadata deleted, and if persisted the contents will also be deleted. Deleting a credential will remove any reference to it and its contents from our systems. This action cannot be undone. This action will not revoke or invalidate the credential in any way.

Delete a Credential

delete

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

/credentials/{id}

Deletes all credential metadata and contents from the client. More info about Delete Credentials

Authorizations

bearerAuthaccessTokennextAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstring · uri · min: 8Required

Valid URI

Example: https://credentials.truvera.io/1234

Query parameters

passwordstring · min: 4 · max: 64Optional

The encryption password used when issuing/storing the credential

Responses

200

Credential has been deleted.

application/json

Responseobject

400

Error retrieving the credential

application/json

404

Credential was not found.

application/json

delete

/credentials/{id}

HTTPcURLJavaScriptPython

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

{}