API Reference
API Limitations
API version 1.0.0 does not define or guarantee this behavior. Design the integration within these limits.
| Area | Limitation | See |
|---|---|---|
| Session status lookup | No public endpoint gets the session status by session_id. The exchange endpoint accepts only an exchange_code and cannot poll the status. | Session Lifecycle |
| Session lifetime | Use the returned expires_at. A fixed session duration is not guaranteed. | Session Lifecycle |
| Rate limits | Numeric rate limits are not published. Handle 429 rate_limited by reducing the request rate. | API Reference Introduction |
| Callback delivery | Retries, delivery order, and exactly-once delivery are not guaranteed. The maximum callback response time is 60 seconds. No transport-level authentication is defined beyond the signed JWT payload. | Server Callback |
| Request idempotency | No idempotency mechanism is defined for the POST endpoints. Deduplicate result processing by session_id. | API Reference Introduction |
privy:cancel reason | Treat this value as opaque. | Web Integration |
verification.method | Treat this value as opaque. | Verify the JWT |
| JWKS rotation | A key-rotation schedule is not published. Select the key that matches the JWT kid header on each verification. | Verify the JWT |
GET /healthz body | No response body is defined. The HTTP 200 status shows health. | API Reference Introduction |
| Blocked-session recovery | The public API contract does not define the retry policy after 423 session_blocked. Raise the case through your agreed Privy support process. | Error Catalog |
| Widget resumption | You can load an unexpired session_url again. Exact resumption at the same widget step is not guaranteed. | Session Lifecycle |
Support and escalation channels, service-level commitments, and the versioning and deprecation policy are agreed with your Privy account team.
Last modified on