Skip to main content

Sessions & refresh

A session is a refresh token plus the access tokens it mints. There are three shapes, chosen at login by what you send.

Web session​

Log in with ?web=true. The refresh token is set as an HttpOnly cookie (not in the response body), which is what you want for a browser. Default lifetime: 30 days.

Device (mobile) session​

A mobile app declares a device at login by sending a device object. It gets a longer, device-bound, sliding session and a stable device identity.

{
  "email": "[email protected]",
  "password": "…",
  "audience": "https://api.acme.com",
  "device": { "name": "Ana's iPhone", "platform": "ios" }
}
  • The response includes a server-issued deviceId. Store it and resend it on the next login — that is how the same phone is recognised instead of piling up duplicate device rows.
  • The access token carries a device_id claim.
  • Default lifetime: 90 days, sliding — every refresh pushes the expiry to now + TTL, so an active device stays signed in and an idle one lapses.

Users can see and revoke their own devices:

  • GET /api/users/me/devices
  • DELETE /api/users/me/devices/{deviceId} — logs that device out; other devices are untouched.

Plain (non-web, non-device) session​

Log in with neither ?web=true nor a device object and the 30-day refresh token is returned in the body. Useful for scripts and back-end integrations.

Per-application session length​

Each application can override how long its refresh tokens live — separately for web and device — within platform bounds of 1 to 180 days. Leave it unset to inherit the platform default (web 30 / device 90). Set it when you register or manage the application; a regulated app can go shorter, a consumer mobile app longer.

Refreshing​

POST /api/auth/refresh with the current refresh token returns a new access token and a new refresh token — the old one is now dead. Always persist the new refresh token. Replaying an old one is treated as theft and revokes the whole session family. The SDKs handle rotation for you.