# 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:

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

The response contains the widget URL:

```json
{
  "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:

```html
<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:

```js
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:

```bash
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:

```json
{
  "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](/digital-id/guides/verify-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](/digital-id/guides/production-readiness) checklist
before you go live.