Skip to main content

Issue a Credential

This integration guide describes how to create and issue a verifiable credential using the API.

Steps​

  1. Create a Template: Define the structure and metadata of the credential you want to issue.

  2. Create a Credential: Fill the template with the user-specific data via the API.

  3. Offer the Credential: Send a credential offer to the recipient.

  4. Show a QR code (optional): If applicable, display a QR code which can be scanned by the recipient to receive the credential.

  5. Check status (optional): Query the status of the credential offer.

1. Create a Template​

A template defines the structure and metadata of a verifiable credential.

warning

The visual Template Builder in UniTrust is still under development, but you can Import an existing template in UniTrust.

If you already have a template to use, you can skip this step.

2. Create a Credential​

To create a credential based on a template, make a POST request to the /v0/credentials endpoint and provide the data as described here.

warning

Currently, a credentialConfigurationId is required when creating a credential. You can find the credentialConfigurationId by inspecting the Credential Issuer Metadata. This step is deprecated and will not be necessary any longer in the upcoming beta release.

  • You also need to supply an offerId which can be any unique string (e.g. a UUID). You need to keep track of this ID to use it in the next step.
info

In a future release, providing the offerId yourself might be optional. It would then be generated for you, if not specified.

  • Choose a timestamp after which the credential will automatically expire. You can also provide "expiresAt": "never", if you want this credential to be valid forever (it can still be manually revoked).
  • Finally, fill the credential object with the content of the credential according to the selected template. The credentialSubject contains the actual content of the credential which will be visible in the user's wallet.

3. Offer the Credential​

After the credential has been created successfully, it needs to be securely transmitted to the intended recipient. They can choose to accept and store it or possibly reject it. The recipient is made aware of the credential through an "offer".

info

The offer only contains metadata about the credential, not the actual credential data. The credential is only transmitted after the recipient has accepted the offer.

To create a credential offer, you can make a POST request to the /v0/offers endpoint where you only need to provide the offerId which you also used in the previous step when creating the credential. You should receive an URL-encoded string starting with openid-credential-offer://. All compatible identity wallets know how to interpret this scheme.

4. Render a QR code (optional)​

In most cases, the offer is presented to the user through a QR code that they can scan with their mobile wallet. The URL-encoded offer string from the previous step can be rendered with any QR code library of your choice. Make sure to use it exactly as provided without any further encodings or string manipulations (such as extra quotes).

5. Check status (optional)​

To further enhance the integration and user experience, you can fetch the status of the credential offer by making a simple GET request to the /v0/offers/{offerId} endpoint. The status field allows you to determine whether the recipient has accepted or rejected the offer or if it's still pending. You can use this information to update your application flow accordingly.

tip

It is also possible to set up notifications about status changes which avoids the need for constant polling. You can listen for all kinds of events on a customizable HTTP endpoint or subscribe to a message queue (currently only NATS is supported).