Skip to content

Latest commit

 

History

History
276 lines (177 loc) · 11.1 KB

issue-credential.md

File metadata and controls

276 lines (177 loc) · 11.1 KB
description
Issue conformant W3C Verifiable Credentials over REST API

Issue Credential

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 accountSet up your account with cheqd Studio and log in to start using the APIs.set-up-account.md

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 DIDCreate a W3C conformant DID on cheqd using the did:cheqd DID Method.create-did.md

(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 DIDCreate an off-ledger did:key or did:vda Subject DID to receive a Verifiable Credential.create-subject-did.md
Setup Verida WalletLearn about setting up your Verida wallet to receive a did:vda address.verida.md

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.

{% swagger src="https://raw.githubusercontent.com/cheqd/credential-service/main/src/static/swagger-api.json" path="/credential/issue" method="post" expanded="true" %} https://raw.githubusercontent.com/cheqd/credential-service/main/src/static/swagger-api.json {% endswagger %}

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
}

{% hint style="info" %} Ensure that the "statusPurpose" and "statusListName" is the same as the existing Status List on-ledger. {% endhint %}

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.

{% swagger src="https://raw.githubusercontent.com/cheqd/credential-service/main/src/static/swagger-api.json" path="/credential/issue" method="post" expanded="true" %} https://raw.githubusercontent.com/cheqd/credential-service/main/src/static/swagger-api.json {% endswagger %}

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 PluginThe Veramo SDK Plugin is an extension of the Veramo SDK, a JavaScript framework for Trusted Data, adding support for cheqd functionality.veramo-plugin
CredoCredo is an SDK which supports ZKCreds (AnonCreds) and regular Verifiable Credentials natively with cheqd support. credo.md
Walt.id SSI KitWalt.id SSI Kit is an SDK that supports the European Architecture and Reference Framework (ARF) standards for identity, with full cheqd support. ssi-kit.md

t