Skip to main content

Sessions

Beta

This feature is in beta. Core behavior is stable and ready to try, but some APIs or configuration may still evolve before general availability.

Manage user sessions across multiple devices.

List Sessions​

const { sessions } = await client.auth.listSessions();
// sessions: [{ id, createdAt, expiresAt, ip, userAgent, lastActiveAt }, ...]

Revoke a Session​

await client.auth.revokeSession('session-id');

Multi-Device Support​

EdgeBase supports multiple simultaneous sessions per user. Each sign-in creates a new session with:

  • IP address — Client IP at sign-in time
  • User-Agent — Browser/device info
  • Last activity — Updated on token refresh

Refresh Token Rotation​

Each current-token refresh issues one replacement. The previous token remains a bounded retry alias for that same replacement:

Client → POST /auth/refresh (old refreshToken)
Server → { accessToken: "new...", refreshToken: "new..." }
         (old refreshToken enters the 30-second previous-token grace path)

A 30-second grace period allows in-flight requests using the previous refresh token to succeed.

Grace Period Details​

When a refresh token is rotated, the previous token remains valid for 30 seconds. This prevents race conditions when multiple browser tabs or concurrent requests attempt to refresh the token simultaneously.

  • During the 30-second window, the previous token returns the already-winning current replacement; it never triggers another rotation branch
  • After the 30-second window expires, using the old token triggers token theft detection -- the session is revoked
  • This protects against stolen refresh tokens while being tolerant of normal concurrent usage patterns

Session Limits (maxActiveSessions)​

Control the maximum number of concurrent sessions per user. When the limit is reached, the oldest session is evicted (FIFO) to make room for the new sign-in.

auth: {
  session: {
    maxActiveSessions: 5  // 0 = unlimited (default)
  }
}
Config ValueBehavior
0 (default)Unlimited sessions
1Single session only -- new sign-in evicts the previous session
5Up to 5 concurrent sessions; oldest evicted when limit is reached

The oldest session (by createdAt) is deleted to make room for the new session. See Session Management for detailed eviction logic and examples.

Token Lifetimes​

TokenDefault TTLStorage
Access Token15 minutesMemory only
Refresh Token28 daysLegacy Web body mode: localStorage; recommended Web cookie mode: EdgeBase __Host- HttpOnly cookie on HTTPS; React Native: app-provided Keychain/Keystore secureStorage

Configure in edgebase.config.ts:

auth: {
  session: {
    accessTokenTTL: '15m',
    refreshTokenTTL: '28d',
  }
}

For browser applications, enable auth.session.cookie on the server and create the Web client with refreshTokenTransport: 'httpOnlyCookie' to keep the refresh credential out of JavaScript-accessible storage. Access tokens remain short-lived Bearer tokens held in memory. HTTPS uses a host-only __Host- cookie with Secure; Path=/; release cookie transport requires HTTPS.

JWT Key Rotation​

Use npx edgebase keys rotate-jwt to rotate JWT_USER_SECRET and JWT_ADMIN_SECRET simultaneously without logging users out:

npx edgebase keys rotate-jwt
npx edgebase deploy  # Required: activate new secrets
  • Old secrets are preserved as JWT_USER_SECRET_OLD / JWT_ADMIN_SECRET_OLD
  • 28-day grace period — matches Refresh Token TTL, so no active user loses their session during rotation
  • Access Tokens (15m TTL) expire naturally — no grace period needed
  • After 28 days the old secrets are automatically ignored
  • A missing, invalid, or future-dated rotation timestamp never enables the old-secret grace path
note

The grace period only covers signature mismatch errors. Expired tokens are rejected regardless.

Next Steps​

  • Session Management — Configure session limits (maxActiveSessions), eviction logic, and cleanup behavior
  • Password Policy — Configure password strength requirements and leaked password detection