Authentication

Peridot ID authentication is cookie-based. After a successful Google sign-in the API sets two HttpOnly cookies on your domain.

The two cookies

Both are HttpOnly; SameSite=Lax. In production the Secure flag is also set, so they are only sent over HTTPS.

Sign-in flow

Browser                    Peridot ID                 Google
   │  POST /v1/auth/login     │                        │
   │  ← {"url": "/v1/auth/google"}                     │
   │  GET  /v1/auth/google ──►│  302 ─────────────────►│  consent screen
   │  ◄──────────────────────  │                        │
   │  ◄───────────────────────────── 302 + auth code ──  │
   │  GET  /v1/auth/google/callback?code=...            │
   │                        │  exchange code, create or link identity
   │  ◄─ 302 CLIENT_SUCCESS_URL + peridot_access + peridot_refresh cookies

1. Call POST /v1/auth/login (or use the SDK) to get the Google authorization URL.
2. Navigate the browser to that URL. The user consents on Google.
3. Google redirects to GET /v1/auth/google/callback?code=.... The API exchanges the code, creates or links the identity, and issues both session cookies.
4. The browser lands on CLIENT_SUCCESS_URL with a logged-in session.

For a first-time sign-in the API creates an identity, a profile (pre-filled from the Google account), and a linked auth account. Subsequent sign-ins link to the same identity.

Note: GET /v1/auth/google and /v1/auth/google/callback are browser-navigation only. They respond with 302 redirects that a fetch()/Swagger "Send" call cannot follow (the cross-origin redirect to Google is CORS-blocked, showing Failed to fetch). Always open the login URL in a browser tab — never call these two endpoints from JavaScript.

Refreshing tokens

The access token expires after 15 minutes. Instead of asking the user to log in again, call POST /v1/auth/refresh. It:

1. Verifies the current peridot_refresh cookie.
2. Revokes it (rotation) and issues a new access + refresh pair as cookies.

Because each refresh token can be used exactly once, a stolen token that is replayed after rotation is rejected.

curl -b cookies.txt -c cookies.txt -X POST https://api.peridot.id/v1/auth/refresh
# 204 No Content — new cookies set, old refresh token revoked

If this returns 401, the refresh token is invalid, expired, or already rotated — the user must sign in again.

Logging out

POST /v1/auth/logout revokes the current refresh token and clears both cookies. It is idempotent — safe to call when already logged out.

curl -b cookies.txt -c cookies.txt -X POST https://api.peridot.id/v1/auth/logout

Security notes

• Access tokens are short-lived; the real secret is the rotating refresh token.
• The refresh cookie's Path=/v1/auth means it is only sent to auth endpoints, reducing the window for cross-route exfiltration.
• Auth endpoints are rate limited (see Errors).