How to Verify a Verifiable Credential

This guide walks you through to verifying a Verifiable Credential using the FortID Verifier 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. The user must have an EUDI-compliant wallet app installed.
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 use the default value "trust_all".

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. For all other parameters more details about setup and impact will be shared soon.

Note: To streamline the developer experience when testing and exploring the API, all examples in this guide include the predefined FortID Issuer and Verifier Playground API keys. To learn more about API key authentication and how to obtain your own API key, see our Using the API-KEY guide.

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:

curl -X POST "https://evs.fortid.com/verification-session/initiate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: 9LFHJCyxgzDjMsFLUf2FfpiI9ZLTlaLi" \
  -d '{
    "credentialDescription": {
      "credentialType": "eu.europa.ec.eudi.pid.1",
      "credentialFormat": "vc+sd-jwt",
      "disclosurePaths": [
        ["given_name"],
        ["family_name"],
        ["age_over_18"]
      ]
    },
    "trustConfig": "trust_all",
    "protocolConfig": {
      "clientIdScheme": "pre-registered",
      "responseMode": "direct_post.jwt"
    }
  }'

Initiate Response Example

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

{
  "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 an Authorization Request represented either by value (URL encoded) or by reference (a link containing a request_uri parameter) 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 FortID Verifier 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:

curl -X GET "https://evs.fortid.com/verification-session/status/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: 9LFHJCyxgzDjMsFLUf2FfpiI9ZLTlaLi"

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

{
  "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.