Issue an email credential

Tutorial on how to issue an email credential using Issuer REST API

Goal

This guide provides a step-by-step tutorial on issuing a credential using the Issuer API. For this use case, we will work with nChain's Email Credential template. It is assumed that you are already familiar with basic API concepts, including authentication and authorization.

Prerequisite:

• Issuer API Base URL

• Valid Issuer ApiKey

• Valid JWT Access Token

• Valid role of Issuer Admin

Claiming credentials with the nChain Identity wallet app is beyond the scope of this tutorial.

Guide

1

Choosing a Credential template

The first step is to fetch all available credential templates and select the one that fits your use case. A credential template defines the types and configurations required for issuing a credential, ensuring the data provided during issuance aligns with the expected schema.

To retrieve credential templates for the nChain organization (identified by its correlationId), send a request similar to the following:

curl --location '<ISSUER_API_BASE_URL>/public/nchain/.well-known/openid-credential-issuer'

Make sure to replace <ISSUER_API_BASE_URL> with the Issuer API base URL provided to you. If the Issuer is configured with a different correlationId than nChain, update the URL path accordingly.

The response will return a large JSON object containing all supported credentials. For this use case, the key area of focus is the credentials_supported array. Within this array, locate the configuration for the Email Credential, specifically the credentialSubject object.

In the credentialSubject object:

• The only required field is email, which must be a valid email address.

Additionally, an id field, referred to as the credentialId, will be used in the next step.

Keep these details in mind as you proceed to the next section. If desired, feel free to explore other, potentially more complex, credential templates for additional insights.

View full API documentation for endpoint used in this section

2

Create a Credential

Now that we have the blueprint for the Email Credential, we can interact with the Issuer API to request its creation. It’s important to note that when we create a credential, we are preparing it to be claimed by the intended recipient.

curl --location '<ISSUER_API_BASE_URL>/private/credential-offers' \
--header 'Authorization: Bearer <JWT_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "credentialOffers": [
    {
      "credentialId": "emailCredential",
      "credentialDataSupplierInput": {
        "email": "<EMAIL>"
      }
    }
  ],
  "correlationId": "nchain"
}'

In addition to the previously mentioned <ISSUER_API_BASE_URL> variable, you will also need to include a valid JWT access token in place of <JWT_ACCESS_TOKEN>.

For the request body:

• The correlationId must match the one used in the previous step, where we fetched the credential templates.

• The credentialOffers array allows you to create multiple credentials in a single request. However, for this use case, we only need to create one.

• Each object inside the credentialOffers array must include:

  • A credentialId (retrieved from Step 1).

  • A data object containing the information required to create the credential. For the Email Credential, only a valid email address is required in place of <EMAIL>.

Upon a successful response:

• The credentialOffers array will list the credentials created successfully.

• Any failed credential offers can be found in the failedCredentialOffers array.

• The status field of our credential offer should display ready_to_claim.

Finally, save the id field (a UUID value) from the response for use in the next step.

View full API documentation for endpoint used in this section

3

Retrieve Credential claim data

Now that the credential has been created, the next step is to fetch the "claim" data.

curl --location '<ISSUER_API_BASE_URL>/private/credential-offers/c0ed92de-e26d-4fbd-8596-76d982891603/claim' \
--header 'Authorization: Bearer <JWT_ACCESS_TOKEN>'

Upon a successful response, you will receive a field called uri, which contains the URI for claiming the credential. How you use this URI and present it to your users is entirely up to you. Note that the uri is a not a URL that the browsers can read. Its something that the wallet can read. Presenting this as a QR code is the best way for the end user to interact with on the wallet.

View full API documentation for endpoint used in this section

Conclusion

Congratulations! You have just implemented nChain's Issuer API to issuer a Verifiable Credential (VC). Issuing a credential involves selecting a predefined template, creating the credential and securely sharing it with the holder.

This process ensures a streamlined and secure method of issuing verifiable credentials that comply with industry standards.