Security

The merchant credentials are the merchant API key and, with the Identity package, the RSA private key.

Required controls

Apply these controls to each Digital ID integration:

1. Keep X-API-Key on the merchant backend.
2. Create sessions only from the merchant backend.
3. Validate event.origin for each postMessage event.
4. Accept events only from the configured widget origin.
5. Verify the JWT signature and the aud, exp, and iss claims.
6. Keep the RSA private key in the merchant backend secret manager.
7. Decrypt my_identity only after successful JWT verification.
8. Add allow="camera" to the iframe.
9. Register the merchant origin in the Privy allowlist.
10. Base business decisions only on the Privy-signed JWT after backend verification. This applies to a JWT from the exchange or the callback.

Exchange code and session URL

The exchange code is single-use and has a short lifetime. It also requires the merchant API key. It can travel through the front channel, but the merchant must exchange it on the backend.

Treat session_url as sensitive. Do not log or expose the full URL.

Embedder trust model

Privy sends data and tokens only to a verified iframe embedder. An unknown host receives an event type without a payload.

A native WebView is a trusted host and receives the complete result payload. The merchant must still process tokens and private identity data on the backend.

Do not make a business decision from front-channel data alone. The authoritative result is the Privy-signed JWT after the merchant backend verifies it. The exchange and the callback are two delivery channels for that result. Deduplicate processing by session_id.