Exchange a one-time SSO code for the identity
Consumes a `pid_code` issued by a Google or passkey login with `returnTo` (optionally bound to a `clientId`) and returns the PeridotID identity. Codes are single-use and expire after ~5 minutes. Call server-to-server; when the code is bound to an app, the same `clientId` must be presented.
Consumes a pid_code issued by a Google or passkey login with returnTo
(optionally bound to a clientId) and returns the PeridotID identity.
Codes are single-use and expire after ~5 minutes. Call server-to-server;
when the code is bound to an app, the same clientId must be presented.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/auth/exchange" \ -H "Content-Type: application/json" \ -d '{ "code": "mF8xQ2vT9nR4kL7pZ3wX6yA1bD5eF0gH", "clientId": "pidapp_0123456789abcdef0123456789abcdef" }'{ "pid": "ifal@pid", "identityId": "ifal@pid", "profile": { "displayName": "string", "avatarUrl": "string" }, "credentials": [ { "provider": "string", "email": "string" } ]}Claim a pending credential under a fresh PID handle POST
One transaction creates the identity (`<handle>@pid`, permanent) + profile + credential and consumes the single-use claim ticket. Issues the session cookies. When the claim came from a relying-party login, the response also carries the SSO `pidCode` plus the validated `redirectTo` — the hosted page navigates there itself. Expired tickets answer `410` — sign in again.
Start Google login POST
Returns the URL a client should navigate to in order to begin Google OAuth. The URL points to `GET /auth/google`, which redirects the browser to Google's consent screen. After the user consents, the browser is redirected back through `/auth/google/callback` and session cookies are set. For cross-origin SSO, pass `returnTo` (must be allowlisted, or registered to your app via `clientId`) — the callback then redirects to `returnTo?pid_code=...` with a one-time exchange code instead of the wallet. First-time users always land on the PID picker after authenticating (`POST /v1/auth/claim` creates the permanent `<handle>@pid` identity) — handles are only ever chosen there, never up front. Returning logins continue straight to a session.