Verify an email credential

Tutorial on how to start the Credential verification process

Goal

This tutorial walks you through the process of verifying a credential using the Verifier API. The goal is to fetch the Auth Request URI for the selected credential type/template, present it in a user-friendly format (e.g., a QR code), and enable the user to scan it with their Wallet app. While the Wallet app's scanning process is outside the scope of this guide, we will cover everything necessary to prepare for successful verification.

Prerequisite:

• Verifier API Base URL

• Valid Verifier ApiKey

• Valid role of Verifier Admin

• Credential template ID, also known as the definitionId

Guide

1

Getting stared

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

For reference review the Getting Started

2

Prepare credential template ID

The only dynamic variable required for the request is the Credential Template ID, also referred to as the definitionId or credentialId (commonly on the Issuer API side). This is typically a camelCase string representing the type of credential. For example, in the case of an email credential, the ID is emailCredential.

There are two common methods to locate this information:

1. Retrieve the Credential ID from a Verifiable Credential:

   • Use the ID of the Issuer's Verifiable Credential to fetch its details via the Issuer API.

   • Call the "Fetch One Credential Offer" endpoint.

   • In the successful response, locate the credentialId field, which represents the Credential Template ID.

2. Search in the List of Credential Types:

   • Use the Issuer API to list all credential types and their metadata by calling the appropriate endpoint.

   • Look for your desired credential type in the credentials_supported array.

   • The value you need is the id field in the corresponding data object.

   • Read more about this endpoint here.

3

Fetch verification information

To retrieve the authRequestURI for the credential, send a request to the Verifier API using the following steps:

$API_KEY=INSERT_YOUR_API_KEY_HERE
$IDENTITY_ENV_ID=426f1ce15bf3df70
$VERIFIER_API_BASE_URL=https://identity.nchainplatform.com/products/web/$IDENTITY_ENV_ID/verifier/api
curl --location --request POST '$VERIFIER_API_BASE_URL/private/verifiable-presentations/<DEFINITION_ID>' \
--header 'X-API-KEY: $API_KEY'

• Replace the placeholder values in $VERIFIER_API_BASE_URL and $API_KEY with the actual API base URL and a valid access token for your setup.

• For <DEFINITION_ID>, use the Credential Template ID you obtained in Step 2 of this guide.

Upon a successful response, you will receive a data object containing the authRequestURI field. The correlationId is used as the record reference id which can be used in subsequent request to the API.

Important: The authRequestURI is not a standard URL that can be accessed through a browser. It is specifically designed to be readable by compatible Wallet apps for credential verification.

View full API documentation for endpoint used in this section

4

Present the verification URI

Once you have obtained the authRequestURI, present it in a format that the user can easily interact with. The most user-friendly option is to generate a QR code, which the user can scan with their Wallet app to initiate the verification process.

5

Monitor the verification status (API Key auth)

After preparing the verification URI, you can track the status of the verification process by polling the GET /verifiable-presentations/:credentialId endpoint.

curl --location '$VERIFIER_API_BASE_URL/private/verifiable-presentations/<CORRELATION_ID>' \
--header 'X-API-KEY: $API_KEY' \
--header 'Content-Type: application/json' \

Along with the previously mentioned $VERIFIER_API_BASE_URL, $API_KEY, you’ll need to include the <CORRELATION_ID> in the request url. This value is returned from the response in the previous step, look for the correlationId value.

When you call the Auth Status endpoint, look for the status field in the response to monitor the progress. The status can indicate various stages:

• created,

• scanned,

• failed,

• valid,

• error

View full API documentation for endpoint used in this section

Conclusion

By following this tutorial, you can successfully set up and manage the process of verifying a credential using the Verifier API. Fetching the authRequestURI, presenting it to users, and integrating Wallet app interactions are key steps in creating a seamless and secure verification workflow. While the Wallet app’s scanning process is beyond the scope of this guide, you now have a comprehensive understanding of how to use the Verifier API to facilitate credential verification.