Session Lifecycle

A session is one verification attempt. Privy generates its session_id when the merchant backend calls POST /v1/sessions.

The same session_id appears in:

• The create-session response.
• Each front-channel widget event.
• The exchange response and the server callback.
• The session_id claim of the verified-data JWT.

Use session_id to correlate front-channel activity with the backend result. Also use it to deduplicate result processing.

A session_id alone does not prove that verification succeeded. API version 1.0.0 has no endpoint that gets the session status by session_id. POST /v1/sessions/exchange cannot poll the status. It accepts only a single-use exchange_code that Privy issues after successful verification. The only authoritative evidence of success is the Privy-signed JWT after the merchant backend verifies it.

Create-session timeout

If the create-session request times out, the merchant backend does not receive session_url, and the widget cannot load. Create a new session. The retry can return a new session_id. The previous unused session expires automatically and is not charged.

Verification in progress

Keep the active session_id, session_url, and expires_at on the merchant backend while verification is in progress. Use the returned expires_at. A fixed session duration is not guaranteed.

The user can interrupt the flow, for example by closing the application. If the same session_url is available and has not expired, you can load it again. Exact resumption at the same widget step is not guaranteed.

If session_url is not available or the session expired, create a new session. The user starts the flow again.

Treat session_url as sensitive. It gives access to the verification widget for that session. Do not log or expose the full URL.