Issue a Verifiable Credential

Issue W3C conformant Verifiable Credentials over REST API, using cheqd Studio.

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:

Set Up Your Account

Set up your account with cheqd Studio and log in to start using the APIs.

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:

Create an Issuer DID

Create a W3C conformant DID on cheqd using the did:cheqd DID Method.

(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:

Create a Subject DID

Create an off-ledger did:key or did:vda Subject DID to receive a Verifiable Credential.

Setup Verida Wallet

Learn about setting up your Verida wallet to receive a did:vda address.

It is also possible to use a did:cheqd DID for holders and subjects, but this is only recommended when the holder is not a natural person (e.g. is an AI Agent, organisation or object).

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.

Issue a Verifiable Credential

post

This endpoint issues a Verifiable Credential. As input it takes the list of issuerDid, subjectDid, attributes, and other parameters of the credential to be issued.

Authorizations

Body

application/x-www-form-urlencodedapplication/json

Input fields for the creating a Verifiable Credential.

issuerDidstringRequired

DID of the Verifiable Credential issuer. This needs to be a did:cheqd DID.

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

subjectDidstringRequired

DID of the Verifiable Credential holder/subject. This needs to be a did:key DID.

Example: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

attributesobjectRequired

JSON object containing the attributes to be included in the credential.

Example: {"name":"Bob","gender":"male"}

@contextstring[]Optional

Optional properties to be included in the @context property of the credential.

Example: ["https://schema.org/schema.jsonld","https://veramo.io/contexts/profile/v1"]

typestring[]Optional

Optional properties to be included in the type property of the credential.

Example: ["Person"]

expirationDatestring · date-timeOptional

Optional expiration date according to the <a href=https://www.w3.org/TR/vc-data-model/#expiration> VC Data Model specification.

Example: 2023-06-08T13:49:28.000Z

formatstring · enumOptional

Format of the Verifiable Credential. Defaults to VC-JWT.

Example: jwtPossible values:

termsOfUseobject[]Optional

Terms of use can be utilized by an issuer or a holder to communicate the terms under which a verifiable credential was issued.

Example: {"type":"IssuerPolicy","id":"http://example.com/policies/credential/4","profile":"http://example.com/profiles/credential","prohibition":[{"assigner":"https://example.edu/issuers/14","assignee":"AllVerifiers","target":"http://example.edu/credentials/3732","action":["Archival"]}]}

refreshServiceobject[]Optional

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.

Example: {"type":"ManualRefreshService2018","id":"https://example.edu/refresh/3732"}

evidenceobject[]Optional

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.

Example: {"type":["DocumentVerification"],"id":"https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231","verifier":"https://example.edu/issuers/14","evidenceDocument":"DriversLicense","subjectPresence":"Physical","documentPresence":"Physical","licenseNumber":"123AB4567"}

Responses

200

The request was successful.

application/json

400

A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.

401

Access token is missing or invalid

500

An internal error has occurred. Additional state information plus metadata may be available in the response body.

post

HTTPcURLJavaScriptPython

POST /credential/issue HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 364

"issuerDid='did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0'&subjectDid='did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'&attributes={'gender':'male','name':'Bob'}&@context=['https://schema.org']&type=['Person']&format='jwt'&credentialStatus={'statusPurpose':'revocation','statusListName':'employee-credentials','statusListIndex':10}"

application/x-www-form-urlencodedapplication/json

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://schema.org",
    "https://veramo.io/contexts/profile/v1"
  ],
  "credentialSubject": {
    "gender": "male",
    "id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "name": "Bob"
  },
  "credentialStatus": {
    "id": "https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:7c2b990c-3d05-4ebf-91af-f4f4d0091d2e?resourceName=cheqd-suspension-1&resourceType=StatusList2021Suspension#20",
    "statusIndex": 20,
    "statusPurpose": "suspension",
    "type": "StatusList2021Entry"
  },
  "issuanceDate": "2023-06-08T13:49:28.000Z",
  "issuer": {
    "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0"
  },
  "proof": {
    "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkaWQ6Y2hlcWQ6dGVzdG5ldDo3YmY4MWEyMC02MzNjLTRjYzctYmM0YS01YTQ1ODAxMDA1ZTAiLCJuYmYiOjE2ODYyMzIxNjgsInN1YiI6ImRpZDprZXk6ejZNa2hhWGdCWkR2b3REa0w1MjU3ZmFpenRpR2lDMlF0S0xHcGJubkVHdGEyZG9LIiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3NjaGVtYS5vcmciLCJodHRwczovL3ZlcmFtby5pby9jb250ZXh0cy9wcm9maWxlL3YxIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImdlbmRlciI6Im1hbGUiLCJuYW1lIjoiQm9iIn0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJQZXJzb24iXX19.wMfdR6RtyAZA4eoWya5Aw97wwER2Cm5Guk780Xw8H9fA3sfudIJeLRLboqixpTchqSbYeA7KbuCTAnLgXTD_Cg",
    "type": "JwtProof2020"
  },
  "type": [
    "VerifiableCredential",
    "Person"
  ]
}

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:

issuerDid (required)

This is the DID of the Credential issuer, created in Step 2. This needs to be a did:cheqd DID. For example:

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

subjectDid (required)

This is the DID of the Credential subject, created in Step 3. This needs to be a did:key or did:vda DID. For example:

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

attributes (required)

These are the claims or attributes attested to within the Verifiable Credential. This must be a JSON object, following the syntax defined in the Verifiable Credential Data Model. For example:

{
  "name": "Bob",
  "gender": "male"
}

credentialSchema (required for Verida wallet)

This is the Schema which the Credential body takes the form of. For the Verida wallet, to display a credential, it needs to have a schema associated with it.

https://common.schemas.verida.io/health/pathology/tests/covid19/pcr/v0.1.0/schema.json

@context (optional)

This is an optional property that defines semantic information about the Credential, conforming to the @contexts section of the Verifiable Credential Data Model. For example:

https://www.w3.org/2018/credentials/v1

type (optional)

This is an optional property that defines information about the type of Verifiable Credential, conforming to the types section of the Verifiable Credential Data Model. For example:

VerifiableCredential

expirationDate (optional)

This is an optional property that defines information about the expiration date of a Verifiable Credential, conforming to the expiration section of the Verifiable Credentials Data Model. For example:

2023-06-08T13:49:28.000Z

format (optional)

Format of the Verifiable Credential. Defaults to VC-JWT.

• jwt (VC-JWT)

• lds (JSON-LD)

credentialStatus (optional)

credentialStatus properties for VC revocation or suspension. Takes statusListName and statusListPurpose as inputs. If you have already created a Status List, you can include the same inputs here to map this issued credential within the created bitstring.

Note that this is the same for unencrypted Status Lists and for encrypted Status Lists. For example:

{
  "statusPurpose": "revocation",
  "statusListName": "employee-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:

Example Request Format: Random Bitstring index

{
  "statusPurpose": "revocation",
  "statusListName": "employee-credentials"
}

Example Request Format: Specified Bitstring index

{
  "statusPurpose": "revocation",
  "statusListName": "employee-credentials",
  "statusListIndex": 1543
}

Example Request Format: Bitstring index within a given range

{
  "statusPurpose": "revocation",
  "statusListName": "employee-credentials"
  "statusListRangeStart": 1000,
  "statusListRangeEnd": 2000
}

Example Request Format: Bitstring including omitted bits

{
  "statusPurpose": "revocation",
  "statusListName": "employee-credentials"
  "statusListRangeStart": 1000,
  "statusListRangeEnd": 2000,
  "indexNotIn": 1001. 1264. 1268, 1854
}

Ensure that the "statusPurpose" and "statusListName" is the same as the existing Status List on-ledger.

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:

{
  "issuerDid": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
  "subjectDid": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "attributes": {
    "gender": "male",
    "name": "Bob"
  },
  "@context": [
    "https://schema.org"
  ],
  "type": [
    "Person"
  ],
  "credentialSchema": "https://common.schemas.verida.io/identity/kyc/FinClusive/individual-basic/v0.1.0/schema.json",
  "format": "jwt",
  "credentialStatus": {
    "statusPurpose": "revocation",
    "statusListName": "employee-credentials",
    "statusListIndex": 10
  }
}

Step 5: Issue a Credential using the API below

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

Issue a Verifiable Credential

post

This endpoint issues a Verifiable Credential. As input it takes the list of issuerDid, subjectDid, attributes, and other parameters of the credential to be issued.

Authorizations

Body

application/x-www-form-urlencodedapplication/json

Input fields for the creating a Verifiable Credential.

issuerDidstringRequired

DID of the Verifiable Credential issuer. This needs to be a did:cheqd DID.

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

subjectDidstringRequired

DID of the Verifiable Credential holder/subject. This needs to be a did:key DID.

Example: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

attributesobjectRequired

JSON object containing the attributes to be included in the credential.

Example: {"name":"Bob","gender":"male"}

@contextstring[]Optional

Optional properties to be included in the @context property of the credential.

Example: ["https://schema.org/schema.jsonld","https://veramo.io/contexts/profile/v1"]

typestring[]Optional

Optional properties to be included in the type property of the credential.

Example: ["Person"]

expirationDatestring · date-timeOptional

Optional expiration date according to the <a href=https://www.w3.org/TR/vc-data-model/#expiration> VC Data Model specification.

Example: 2023-06-08T13:49:28.000Z

formatstring · enumOptional

Format of the Verifiable Credential. Defaults to VC-JWT.

Example: jwtPossible values:

termsOfUseobject[]Optional

Terms of use can be utilized by an issuer or a holder to communicate the terms under which a verifiable credential was issued.

Example: {"type":"IssuerPolicy","id":"http://example.com/policies/credential/4","profile":"http://example.com/profiles/credential","prohibition":[{"assigner":"https://example.edu/issuers/14","assignee":"AllVerifiers","target":"http://example.edu/credentials/3732","action":["Archival"]}]}

refreshServiceobject[]Optional

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.

Example: {"type":"ManualRefreshService2018","id":"https://example.edu/refresh/3732"}

evidenceobject[]Optional

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.

Example: {"type":["DocumentVerification"],"id":"https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231","verifier":"https://example.edu/issuers/14","evidenceDocument":"DriversLicense","subjectPresence":"Physical","documentPresence":"Physical","licenseNumber":"123AB4567"}

Responses

200

The request was successful.

application/json

400

A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.

401

Access token is missing or invalid

500

An internal error has occurred. Additional state information plus metadata may be available in the response body.

post

HTTPcURLJavaScriptPython

POST /credential/issue HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 364

"issuerDid='did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0'&subjectDid='did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'&attributes={'gender':'male','name':'Bob'}&@context=['https://schema.org']&type=['Person']&format='jwt'&credentialStatus={'statusPurpose':'revocation','statusListName':'employee-credentials','statusListIndex':10}"

application/x-www-form-urlencodedapplication/json

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://schema.org",
    "https://veramo.io/contexts/profile/v1"
  ],
  "credentialSubject": {
    "gender": "male",
    "id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "name": "Bob"
  },
  "credentialStatus": {
    "id": "https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:7c2b990c-3d05-4ebf-91af-f4f4d0091d2e?resourceName=cheqd-suspension-1&resourceType=StatusList2021Suspension#20",
    "statusIndex": 20,
    "statusPurpose": "suspension",
    "type": "StatusList2021Entry"
  },
  "issuanceDate": "2023-06-08T13:49:28.000Z",
  "issuer": {
    "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0"
  },
  "proof": {
    "jwt": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkaWQ6Y2hlcWQ6dGVzdG5ldDo3YmY4MWEyMC02MzNjLTRjYzctYmM0YS01YTQ1ODAxMDA1ZTAiLCJuYmYiOjE2ODYyMzIxNjgsInN1YiI6ImRpZDprZXk6ejZNa2hhWGdCWkR2b3REa0w1MjU3ZmFpenRpR2lDMlF0S0xHcGJubkVHdGEyZG9LIiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3NjaGVtYS5vcmciLCJodHRwczovL3ZlcmFtby5pby9jb250ZXh0cy9wcm9maWxlL3YxIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImdlbmRlciI6Im1hbGUiLCJuYW1lIjoiQm9iIn0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJQZXJzb24iXX19.wMfdR6RtyAZA4eoWya5Aw97wwER2Cm5Guk780Xw8H9fA3sfudIJeLRLboqixpTchqSbYeA7KbuCTAnLgXTD_Cg",
    "type": "JwtProof2020"
  },
  "type": [
    "VerifiableCredential",
    "Person"
  ]
}

Alternatives

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

Veramo SDK Plugin

The Veramo SDK Plugin is an extension of the Veramo SDK, a JavaScript framework for Trusted Data, adding support for cheqd functionality.

Credo

Credo is an SDK which supports ZKCreds (AnonCreds) and regular Verifiable Credentials natively with cheqd support.

ACA-Py

ACA-Py (Aries Cloud Agent Python) is an SDK that can issue AnonCreds, JSON-LD and SD-JWT credentials with full cheqd support.

Walt.id SSI Kit

Walt.id SSI Kit is an SDK that supports the European Architecture and Reference Framework (ARF) standards for identity, with full cheqd support.

t