Skip to content
Documentation

How to Verify a Verifiable Credential

This guide walks you through to verifying a Verifiable Credential using the Verification Service API. The process involves two main steps:

  1. Initiating a verification session
  2. Checking the verification session status

Prerequisites

In order to start with the verification process, there are a few requirements for a user to set prior to it:

  1. User must own an EUDI compliant wallet app
  2. User must have at least one Verifiable Credential issued to their wallet

If you are not sure whether you meet these requirements, this guide will get you covered.

1. Initiate Verification Session

To begin the process, user must initiate a verification session. During this step, user specifies what type of credential they’re expecting to be presented with and how to trust it.

Configuring credential specification includes specifying the type of credential (e.g. org.iso.18013.5.1.mDL), its format (currently supported mso_mdoc and vc+sd-jwt), and list of claims to be disclosed.

Configuring trust policies enables you to set your custom trust rules, but that’s too much detail at this point. For the simplest scenario just leave it empty.

Configuring the protocol details includes defining OpenID4VP specifics such as clientIdScheme or responseMode which is also something you can omit for basic scenarios and fallback to their default values.

Currently the only mandatory values to be sent in initiate request are credentialType and credentialFormat in credentialDescription and trustConfig (which can be left empty for now). For all other parameters more details about setup and impact will be shared soon.

Now that we covered all the basics let’s see a concrete example how to actually initiate a verification session. We’ll start with verifying a PID credential by using the following curl command:

Terminal window
curl -X POST "https://evs.fortid.eu:4000/verification-session/initiate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 123456" \
  -d '{
    "credentialDescription": {
      "credentialType": "eu.europa.ec.eudi.pid.1",
      "credentialFormat": "vc+sd-jwt",
      "disclosurePaths": [
        ["given_name"],
        ["family_name"],
        ["age_over_18"]
      ]
    },
    "trustConfig": [],
    "protocolConfig": {
      "clientIdScheme": "redirect_uri",
      "responseMode": "direct_post.jwt"
    }
  }'

Initiate Response Example

The response will contain two values, verificationSessionId and authorization_request, as you can see in this example:

Terminal window
{
  "verificationSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "authorization_request": "openid4vp://authorize?client_id=..."
}
  • verificationSessionId is a unique ID for verification session which can later be used to obtain verification status through FortID.
  • authorization_request is a URL encoded Authorization Request that can be sent to an external wallet to start the OpenID4VP flow.

Received authorization_request is then given to the wallet, usually via QR code. From this point, the wallet and Verification Service handle the rest of the protocol.

2. Check Verification Status

Once the session was initiated, the result of the verification session can be checked using the following curl command:

Terminal window
curl -X GET "https://evs.fortid.eu:4000/verification-session/status/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 123456"

Note: verificationSessionId from the URL should be replaced with the one received in the initiate response.

Check Status Response

Response of the status check will contain verificationSessionStatus indicating current status of the verification session and optionally an additional information dependent on the status.

Possible Statuses

There are three possible statuses which you can expect to receive under verificationSessionStatus:

  • IN_PROGRESS – verification is still in progress, check again in a few moments. Does not have any additional info.
  • VERIFICATION_SUCCEEDED – credential was successfully verified. In this case, successful response will contain presented claims under additional field presentedClaims.
  • VERIFICATION_FAILED – verification failed, possibly with an error description. In this case, additional field description explaining why it failed will be present.

Successful Response Example

Terminal window
{
  "verificationSessionStatus": "VERIFICATION_SUCCEEDED",
  "presentedClaims": {
    "name": "John",
    "age": 27,
    "address": {
      "street": "Baker Street",
      "postalCode": "NW1"
    },
    "nationalities": ["UK"]
  }
}

Notes

  • Verification sessions automatically expire after a configurable timeout.
  • If you query a session after it expires, you will receive a 404 - Session not found.