Sessions

A successful otp/verify call returns an access_token (15-minute TTL), a refresh_token (configurable per project, default 10 days, max 30 days), and expires_at (access token expiry as ISO 8601). The refresh token has an absolute expiry — it does not extend when used.

Validate a session

Call this on every authenticated request from your app's users:

const res = await fetch('https://api.minimoth.dev/v1/session/validate', {
  method: 'POST',
  headers: { 'X-Api-Key': 'mm_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ access_token }),
})
const { valid, phone, expires_at } = await res.json()
// valid: false on any invalid/expired token — never throws

Refresh a session

const res = await fetch('https://api.minimoth.dev/v1/session/refresh', {
  method: 'POST',
  headers: { 'X-Api-Key': 'mm_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ refresh_token }),
})
const { access_token, refresh_token: new_refresh_token, expires_at } = await res.json()
// Both tokens are rotated on every refresh — store new_refresh_token for the next call.
// 401 if the refresh token has expired or was already used outside the 10-second grace window.
// Beyond the grace window, reuse invalidates all tokens for the session.

Important: every refresh rotates both tokens. Replace the stored refresh_token with new_refresh_token after each call — the old one is immediately invalidated. The refresh token expiry is absolute and does not extend on use.

A 10-second re-hydration window is built in: if the same refresh token is used twice within 10 seconds (e.g. a double-fire during SSR hydration), the second call returns a new access token without triggering invalidation. Beyond 10 seconds, reuse of an already-rotated token invalidates all tokens for the session.

Log out

await fetch('https://api.minimoth.dev/v1/session/logout', {
  method: 'POST',
  headers: { 'X-Api-Key': 'mm_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ access_token }),
})
// idempotent — returns 200 even if the session was already logged out