DocsAPI ReferenceLogin
Auth

Claim a pending credential under a fresh PID handle

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.

POST
/auth/claim

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.

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/claim" \  -H "Content-Type: application/json" \  -d '{    "handle": "ifal"  }'
{  "ok": true,  "pid": "ifal@pid"}

Mint a pid_code for the current session POST

Issues a one-time pid_code for the caller's existing session — no re-authentication. Powers consent screens on PeridotID-hosted pages: the user approves, the page redirects itself to returnTo with the code. Cookie-authenticated (same-site pages only). returnTo follows the same rules as login (loopback, registered app origins, global allowlist).

Exchange a one-time SSO code for the identity POST

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.