Verify credentials

Just like it says on the tin, verifiable credentials are verifiable by design. They contain all the proof needed to enable the owner to answer verification requests directly, without third parties.

Once issued the holder of a credential can accept incoming proof requests to present information to a verifying party. In the same way that you would show a loyalty card to prove you are part of a loyalty program in the physical world, verifiable credentials can be used to prove information in a digital interaction.

This guide contains everything you need to know about verifying credentials with Paradym. It will show you how to to:

Set up a trusted entity.
Create a presentation template
Set up a webhook.
Use a presentation template to verify a credential
View your ongoing verifications and their status

Let’s get started! 🚀

Set up a trusted entity

Create a trusted entity following the trusted entities docs.

Create a presentation template

Create a presentation template following the presentation template docs.

Set up a webhook

To listen for the result of a verification, you can set up a webhook. Whenever an event happens within Paradym, we will notify your application by sending the event to registered webhook URL.

We recommend listening one of the the following event sets, depending on the credential format you’re using:

didcomm.verification.data and didcomm.verification.failed (When verifying Anoncreds credentials)
openid4vc.verification.data and openid4vc.verification.failed (When verifying SD-JWT VC and mDOC credentials)

You can read more on configuring webhooks in the webhook documentation. This covers how to register a webhook, as well as verifying a webhook (which is important to ensure the webhook was sent by Paradym).

💡

You can use a site such as Webhook.site or Request Baskets to get a temporary endpoint to receive events and play around with.

Note that webhook events contain sensitive information, and these services do not verify the HMAC of the events. You should not use these services for production webhooks.

Use a presentation template to verify a credential

The Paradym API currently supports issuing SD-JWT credentials and verifying SD-JWT and mDOC credentials over OpenID4VC, as well as issuance and verification of Anoncreds credentials over DIDComm. Read more about the different standards and protocols.

Based on the credential format you selected in the presentation template, you should either request a presentation over DIDComm or OpenID4VC:

SD-JWT VC (sd-jwt-vc) and mDOC (mdoc) with OpenID4VC Verification .
Anoncreds (anoncreds) with DIDComm Verification .

OpenID4VC API

To verify an sd-jwt-vc and/or mDOC credential using OpenID4VCI based on the created template, we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/openid4vc/verification/request. For detailed information on the endpoint, refer to create OpenID4VC verification request in the API reference.

In the payload below we create a verification request, based on the presentation template we created earlier. Make sure to update the presentationTemplateId to the ID of the presentation template.

You can optionally provide the requireResponseEncryption parameter to ensure the response from the wallet to Paradym will be encrypted (more details in the API reference). We recommend enabling response encryption.


{
  "presentationTemplateId": "clu129ps200043eghxvhz22m1",
  "requireResponseEncryption": true
}

The payload that is returned will look as follows:


{
  "id": "clu6p64z80001c7xudvp2uvts",
  "authorizationRequestUri": "https://paradym.id/invitation?request_uri=https%3A%2F%2Fparadym.id%2Foid4vp%2Fa744eefb-f7e6-444d-8a38-24c0136e893e%2Fauthorization-requests%2F215d6f1a-14fd-47bc-86c8-2b707124718d",
  "status": "requested",
  "presentationTemplateId": "clu129ps200043eghxvhz22m1",
  "credentials": [],
  "createdAt": "2023-01-03T00:00:00.000Z",
  "updatedAt": "2023-01-03T00:00:00.000Z",
  "error": null
}

DIDComm API

To verify an Anoncreds credential using DIDComm based on the created template, we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/didcomm/verification/request. For detailed information on the endpoint, refer to create DIDComm verification request in the API reference.

In the payload below we create a verification request, based on the presentation template we created earlier. Make sure to update the presentationTemplateId to the ID of the presentation template. We will also contain a DIDComm invitation


{
  "didcommInvitation": {
    "createConnection": true,
  },
  "presentationTemplateId": "clu129ps200043eghxvhz22m1"
}

The payload that is returned will look as follows:


{
  "didcommInvitation": {
    "id": "clxeizl1p00kfo7sn9to5d4cl",
    "status": "active",
    "invitationUri": "https://paradym.id/invitation/f927bd5a-9f88-493c-8417-65cb3830097f",
    "reusable": false,
    "createdAt": "2024-06-14T10:08:02.893Z",
    "updatedAt": "2024-06-14T10:08:02.893Z"
  },
  "didcommVerification": {
    "id": "clxeizl2w00kgo7snv6hwymnt",
    "credentials": [],
    "presentationTemplateId": "clu129ps200043eghxvhz22m1",
    "status": "requested",
    "updatedAt": "2024-06-14T10:08:02.937Z",
    "createdAt": "2024-06-14T10:08:02.937Z",
    "didcommInvitationId": "clxeizl1p00kfo7sn9to5d4cl"
  }
}

Directly sending a verification request to a connection

By passing didcommInvitation we will create an invitation that can be shared (as a QR code) with the intended recipient of the verification request. If you’ve already interacted with the recipient in the past, you can also provide a didcommConnectionId instead of didcommInvitation. This will directly send the verification request to the wallet of the holder. You can find connections associated with a previous invitation in the Retrieve DIDComm Connections endpoint and filtering using the filter[didcommInvitationId]=<didcommInvitationId> query.

View the credential data from the verification

Webhook

If you configured a webhook, your application should have received either an openid4vc.verification.data or an didcomm.verification.data event which includes the credential data received in the verification. In case the verification failed, it’s also possible your application received an openid4vc.verification.failed or a didcomm.verification.failed event.

The payload of the openId4VcVerification attribute in the openid4vc.verification.data event, or the didcommVerification attribute in the didcomm.verification.data event, matches the structure from the API.

OpenID4VC API

You can retrieve your created OpenID4VC verification request by making a GET request to https://api.paradym.id/v1/projects/{projectId}/openid4vc/verification/{openId4VcVerificationId} using the id value from the result to the create verification request endpoint. For detailed information on the endpoint, refer to retrieve OpenID4VC verification session in the API reference.

Credential data received in a verification is only available through the API for a limited amount of time. For new projects verification data access is disabled by default and only available through webhooks (webhook), You can change the default “Verification data access” configuration in the project settings in the Dashboard under Settings → Project.

“Verification data access” currently has five options:

webhook - only emit verification data as webhook
once - only allow verification data to be retrieved once, with a limit of 15 minutes.
15min - only allow verification data to be retrieved for 15 minutes
1week (deprecated, see below) - only allow verification data to be retrieved for 1 week
indefinite (deprecated, see below) - allow verification data to be retrieved indefinitely

For new projects the default is to emit verification data as webhooks (webhook), as we recommend to handle it through webhooks. If you can’t rely on webhooks, we recommend setting the access to once (once) or for a maximum of 15 minutes (15min). This should give enough time to fetch the verification data from our API, before it is removed.

For existing projects, we have set the default to indefinite for now (indefinite), to allow for a smoother transition period. You should update your projects to use webhooks (recommended), once (recommend) or 15min.

If the verification data access is set to once, the verification data is only accessible through the “Retrieve verification session by id” endpoints, not through the paginated “Retrieve verification sessions” endpoint.

The 1week and indefinite options are deprecated and only introduced for migration purposes to the newer and shorter retention periods. These options will be removed in the future.

DIDComm API

You can retrieve your created DIDComm verification request by making a GET request to https://api.paradym.id/v1/projects/{projectId}/didcomm/verification/{didcommVerificationId} using the id value of the result to the create verification request endpoint. For detailed information on the endpoint, refer to retrieve DIDComm verification session in the API reference.

“Verification data access” currently has five options:

webhook - only emit verification data as webhook
once - only allow verification data to be retrieved once, with a limit of 15 minutes.
15min - only allow verification data to be retrieved for 15 minutes
1week (deprecated, see below) - only allow verification data to be retrieved for 1 week
indefinite (deprecated, see below) - allow verification data to be retrieved indefinitely

The 1week and indefinite options are deprecated and only introduced for migration purposes to the newer and shorter retention periods. These options will be removed in the future.

That’s it! 🚀

That concludes this guide. You now know how to:

Create a presentation template
Use a presentation template to verify a credential
View your ongoing verifications and their status

If you have any suggestions, remarks or questions, join the Paradym Community and let us know. Happy building!