Verifiers

This page outlines the necessary steps for becoming a verifier on GlobaliD's credential platform.

Prerequisites

Before you become a verifier in our ecosystem, you need to create a Developer App.

Overview

Receiving a verifiable presentation from a holder involves the following steps:

1. Create a deep link.

2. Create a presentation request.

3. Receive the holder's response.

   1. (Optional) verify the message signature.

Here's a high-level sequence diagram that outlines the process:

Check out our library for Node.js to make these steps easier!

Create a Deep Link

To initiate the process of receiving a verifiable presentation, you will need to generate a deep link into GlobaliD's mobile app and present it to a holder. How you present this link depends on your users' experience. For example, on desktop, the link could be displayed as a QR code that a holder scans with their GlobaliD mobile app, while on mobile devices, the link is rendered as a button.

A deep link has a base URL of https://link.global.id/proof and the following query parameters:

• app_uuid - your Developer App's ID (client_id)

• proof_request_url - your app's URL to initiate creating a presentation request

• redirect_url (optional) - location to redirect the holder on their mobile device after responding to your presentation request

Here's an example deep link:

https://link.global.id/proof?app_uuid=01234567-890a-bcde-f012-3456789abcde&proof_request_url=https://your.domain/initiate-presentation

Create a Presentation Request

After a holder activates your deep link, you will receive an HTTP POST request at the corresponding proof_request_url. This is when you need to create a presentation request.

To do so, start by getting an App Access Token. Then make the following request to GlobaliD's API:

POST /v2/aries-management/external-party/proof-requests HTTP/1.1
Host: credentials.global.id
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "proof_requirements": { ... },
  "screening_webhook_url": "https://your.domain/handle-response",
  "tracking_id": "..."
}

• proof_requirements - Submit Requirement Feature object defining the requirements of the credential you would like the holder to present

• screening_webhook_url - your app's URL to receive the holder's response as a webhook

• tracking_id - ID for correlating presentation requests and holder responses

The response should be returned to the holder.

Receive Holder Response

Once the holder responds to the prompts on their device, you will receive an HTTP POST request at the screening_webhook_url corresponding to the presentation request above.

If the holder consents to sharing their credential(s), you'll receive the following payload:

{
  "app_uuid": "{client_id}",
  "tracking_id": "{tracking_id}",
  "thread_id": "...",
  "state": "done",
  "proof_presentation": { ... },
  "verified": true
}

The proof_presentation property will hold a Verifiable Presentation object.

However, if the holder denies the request, you'll receive a rejection:

{
  "app_uuid": "{client_id}",
  "tracking_id": "{tracking_id}",
  "thread_id": "...",
  "error_msg": "...",
  "state": "abandoned",
  "verified": false
}

Verify Message Signature

In either case, you will receive an X-Signature header which contains a digital signature of the response payload. You should verify the signature with GlobaliD's public key, which can be retrieved with the following HTTP request:

GET /v2/aries-management/external-party/public-key HTTP/1.1
Host: credentials.global.id

HTTP/1.1 200 OK
Content-Type: application/json

{
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
}