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 TNG's Email Credential template. It is assumed that you are already familiar with basic API concepts, including authentication and authorisation.

Prerequisite:

• Issuer API Base URL

• Valid Issuer ApiKey

• Valid role of Issuer Admin

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

Guide

1

Getting started

Prepare your working environment with valid values about the Identity environment you want to work on.

For reference review the Getting Started

2

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 TNG organisation (identified by its correlationId), send a request similar to the following:

curl --location '$ISSUER_API_BASE_URL/api/v1/agent/teranode/.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 TNG ('teranode' in example above), 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

3

Fetch working Organisation Profile

To fetch the working Organisation Profile you will need to call the Portal API which is documented GET /api/v1/organisation-profiles/me .

If one does not exist an Admin must create one using POST /api/v1/organisation-profiles

4

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 'X-API-KEY: $API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "credentialOffers": [
    {
      "credentialId": "emailCredential",
      "email": "<RECIPIENT_EMAIL_ADDRESS>",
      "referenceId": "<OPT_REFERENCE_ID_AS_UUID>",
      "expirationDate": "<EXPIRATION_DATE_ISO>"
      "claims": [
       { 
         "dataType": "string",
         "claimName": "email",
         "claimValue": "<EMAIL>"
       }
      ]
    }
  ],
  "credentialOfferCollectionId: "<CREDENTIAL_OFFER_COLLECTION_ID>"
  "organisationProfileId": "<ORGANISATION_PROFILE_ID>"
  "correlationId": "teranode"
}'

In addition to the previously mentioned $ISSUER_API_BASE_URL variable, you will also need to include a valid API Key in place of $API_KEY.

For the request body:

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

• The organisationProfileId must be a valid identifier found on the Portal Backend API

• The credentialOfferCollectionId if defined will bind the credential to a collection which can be later used for filtering. For reference view the API documentation

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

  • credentialId (retrieved from Step 1) defines what credential we want to prepare for issuance.

  • email which defines the recipient of the credential

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

  • referenceId is a custom key you can use to back reference the credential once completed. It is not stored!

  • expirationDate a date-time in iso format defines the expiration date of a credential. If not provided the credential will not expire.

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

5

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/api/v1/credential-offers/c0ed92de-e26d-4fbd-8596-76d982891603/claim' \
--header 'X-API-KEY: <API_KEY>'

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 TNG'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.