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 specificationarrow-up-right. 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 herearrow-up-right.

circle-info

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)

circle-exclamation

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 credentialsarrow-up-right using Zero Knowledge Proofs and Selective Disclosurearrow-up-right 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 Credentialarrow-up-right body to the registry.id value.

circle-info

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
/credentials

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
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
chevron-right
200

The request was successful and returns the created Verifiable Credential.

application/json

Verifiable (signed) Credential returned by API. The current set of properties is almost complete

@contextone ofOptional

JSON-LD context array of strings or single string

Example: https://docknetwork.github.io/vc-schemas/basic-credential.json-ld
or
stringOptional
idstringOptional
typestring[]Optional
credentialSubjectone ofOptional
objectOptional
or
object[]Optional
issuerone ofOptional
string · min: 32Optional

DID as fully qualified, typically. did:cheqd:

Example: did:cheqd:testnet:ac2b9027-ec1a-4ee2-aad1-1e316e7d6f59
or
objectOptional
issuanceDatestring · date-timeOptional
expirationDatestring · date-timeOptional
credentialStatusone ofOptional

Revocation registry id or user supplied status object

objectOptional
or
stringOptional
proofone ofOptional
or
post
/credentials

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
/credentials

Get all credential metadata

Authorizations
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
chevron-right
200

The request was successful and will return the credential metadata.

application/json

Represents metadata related to a verifiable credential. This includes information about the credential's issuer, issuance and expiration dates, revocation status, and additional properties such as size and subject reference.

idstring · uriOptional

The unique identifier for the credential, typically a URL pointing to its location or a hash value.

Example: https://creds.truvera.io/521bb7...
issuerKeystring · nullableOptional

The DID and key identifier of the issuer that signed the credential. This key is used to verify the authenticity of the credential.

Example: did:key:z6Mk...dsmK
issuerNamestring · nullableOptional

The profile name of the issuer that signed the credential.

Example: Truvera Issuer
typestringOptional

The type of credential.

Example: VerifiableCredential
revocationRegistrystringOptional

The registry identifier for revocation information associated with the credential.

Example: e6d3...59d1
revokedbooleanOptional

Indicates whether the credential has been revoked. If true, the credential is no longer valid

Example: false
createdAtstring · date-timeOptional

The date and time when the credential metadata was created.

Example: 2024-09-20T11:13:03.445Z
expiryDatestring · date-time · nullableOptional

The expiration date of the credential.

Example: 2024-09-20T11:13:03.445Z
expirationDatestring · date-time · nullableOptional

Alternative field for the expiration date of the credential.

Example: 2024-09-20T11:13:03.445Z
issuanceDatestring · date-timeOptional

The date and time when the credential was issued.

Example: 2024-09-20T11:13:02.648Z
byteSizeintegerOptional

The size of the credential in bytes.

Example: 1003
persistbooleanOptional

Indicates whether the credential is persisted in storage.

Example: false
indexstringOptional

A unique index or identifier within a collection of credentials.

Example: 1004
subjectRefstringOptional

A reference to the subject of the credential, typically used to identify the entity to which the credential pertains.

Example: Truvera Ref
whitelabelnumber · nullableOptional

Indicates if the credential is associated with a specific whitelabel or brand.

algorithmstring · min: 4 · max: 32Optional

The algorithm used for creating or signing the credential.

Example: dockbbs
get
/credentials

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
/credentials/{id}

Get credential metadata and contents if persistent

Authorizations
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
chevron-right
200

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

application/json

Represents metadata related to a verifiable credential. This includes information about the credential's issuer, issuance and expiration dates, revocation status, and additional properties such as size and subject reference.

idstring · uriOptional

The unique identifier for the credential, typically a URL pointing to its location or a hash value.

Example: https://creds.truvera.io/521bb7...
issuerKeystring · nullableOptional

The DID and key identifier of the issuer that signed the credential. This key is used to verify the authenticity of the credential.

Example: did:key:z6Mk...dsmK
issuerNamestring · nullableOptional

The profile name of the issuer that signed the credential.

Example: Truvera Issuer
typestringOptional

The type of credential.

Example: VerifiableCredential
revocationRegistrystringOptional

The registry identifier for revocation information associated with the credential.

Example: e6d3...59d1
revokedbooleanOptional

Indicates whether the credential has been revoked. If true, the credential is no longer valid

Example: false
createdAtstring · date-timeOptional

The date and time when the credential metadata was created.

Example: 2024-09-20T11:13:03.445Z
expiryDatestring · date-time · nullableOptional

The expiration date of the credential.

Example: 2024-09-20T11:13:03.445Z
expirationDatestring · date-time · nullableOptional

Alternative field for the expiration date of the credential.

Example: 2024-09-20T11:13:03.445Z
issuanceDatestring · date-timeOptional

The date and time when the credential was issued.

Example: 2024-09-20T11:13:02.648Z
byteSizeintegerOptional

The size of the credential in bytes.

Example: 1003
persistbooleanOptional

Indicates whether the credential is persisted in storage.

Example: false
indexstringOptional

A unique index or identifier within a collection of credentials.

Example: 1004
subjectRefstringOptional

A reference to the subject of the credential, typically used to identify the entity to which the credential pertains.

Example: Truvera Ref
whitelabelnumber · nullableOptional

Indicates if the credential is associated with a specific whitelabel or brand.

algorithmstring · min: 4 · max: 32Optional

The algorithm used for creating or signing the credential.

Example: dockbbs
get
/credentials/{id}

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
/credentials/request-claims

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
singleUsebooleanOptionalDefault: true
schemastringOptionalExample: https://docknetwork.github.io/vc-schemas/basic-credential.json
claimsstring[]OptionalExample: name
Responses
chevron-right
200

OpenID issuer and claim request created

application/json

Represents the configuration and options for an OpenID issuer, including credential options, authentication provider details, and claim mappings.

claimMapobjectOptional

Key/value pair mapping for OpenID claims to JSON-LD terms

Example: {"name":"name"}
singleUsebooleanOptionalDefault: false
issuerstringOptional
protocolstringOptionalDefault: default
post
/credentials/request-claims

Get request claims

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

List Credentials

get
/credentials/request-claims

Get all credential metadata

Authorizations
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
chevron-right
200

A paged array of OpenID issuers

application/json

Represents the configuration and options for an OpenID issuer, including credential options, authentication provider details, and claim mappings.

claimMapobjectOptional

Key/value pair mapping for OpenID claims to JSON-LD terms

Example: {"name":"name"}
singleUsebooleanOptionalDefault: false
issuerstringOptional
protocolstringOptionalDefault: default
get
/credentials/request-claims

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
/credentials/{id}

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

Authorizations
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
chevron-right
200

Credential has been deleted.

application/json
objectOptional
delete
/credentials/{id}

Last updated

Was this helpful?