Copy page

Get Started

Quickstart

This procedure creates a verification session, loads the Digital ID widget, and receives the result in the sandbox.

1. Create a session

Send this request from the merchant backend. The request does not have a body:

Code
curl -X POST https://stg-api-digitalid.privy.id/v1/sessions \
  -H "X-API-Key: <MERCHANT_API_KEY>"

The response contains the widget URL:

Code
{
  "session_id": "9f1c2c8a-2d6f-4d60-9ab1-85a5d4aa93d0",
  "session_url": "https://stg-digitalid.privy.id/?t=eyJ...",
  "expires_at": "2026-07-21T18:15:00Z"
}

Keep the API key on the merchant backend. Do not put it in browser or mobile application code.

2. Load the widget

Load session_url in an iframe. Permit camera access:

Code
<iframe
  src="{{session_url}}"
  allow="camera"
  style="width: 100%; height: 100%; border: 0"
></iframe>

Register the merchant origin in the Privy allowlist.

3. Receive the result

Listen for widget events. Accept events only from the expected widget origin:

Code
window.addEventListener("message", (event) => {
  if (event.origin !== "https://stg-digitalid.privy.id") return;

  const { type, payload } = event.data || {};
  if (type === "privy:success") {
    // Send payload.exchange_code to the merchant backend.
  }
});

Send payload.exchange_code to the merchant backend. Exchange it for a verified-data token:

Code
curl -X POST \
  https://stg-api-digitalid.privy.id/v1/sessions/exchange \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <MERCHANT_API_KEY>" \
  -d '{"code":"<EXCHANGE_CODE>"}'

The response contains a Privy-signed JWT:

Code
{
  "session_id": "9f1c2c8a-2d6f-4d60-9ab1-85a5d4aa93d0",
  "event": "identity.verified",
  "token": "eyJ..."
}

Verify the JWT on the merchant backend before you use its data. See Verify the JWT.

Production

Replace the sandbox API and widget hosts with the production hosts. Use the API key that Privy issued for the production environment. Complete the production readiness checklist before you go live.