Session Management

AuthGate provides server-side session management with refresh tokens, giving you long-lived sessions without sacrificing JWT security. Short-lived JWTs handle authorization while refresh tokens maintain the session across token expiry.

Overview

By default, AuthGate issues a short-lived JWT (5 minutes) alongside a long-lived refresh token (30 days) on every successful authentication. The JWT is used for API authorization while the refresh token is used to obtain new JWTs without requiring the user to re-authenticate.

Key characteristics:

• Short-lived JWTs — 5-minute expiry, used for API requests
• Long-lived refresh tokens — 30-day default, configurable per project
• Automatic refresh — the SDK handles token refresh transparently
• Server-side revocation — revoke individual sessions or all sessions for a user
• Backward-compatible — existing JWT-only clients continue working when MFA is off

Refresh tokens

A refresh token is returned alongside the JWT on every successful authentication (OAuth callback, email sign-in, SMS verify, MFA verify).

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_a1b2c3d4e5f6...",
  "user": {
    "id": "user_abc123",
    "email": "jane@example.com",
    "name": "Jane Doe"
  }
}

Refresh tokens are single-use. Each time you exchange a refresh token for a new JWT, you also receive a new refresh token. The old refresh token is invalidated immediately.

Token refresh

Exchange a valid refresh token for a new JWT and refresh token pair.

Request body

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_x9y8z7w6v5u4...",
  "expires_in": 300
}

Error responses

curl -X POST https://auth.example.com/api/proxy/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "rt_a1b2c3d4e5f6..."}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_x9y8z7w6v5u4...",
  "expires_in": 300
}

Session revocation

Revoke a session by invalidating its refresh token. Use this for logout flows.

Request body

Response 200

{
  "success": true
}

Error responses

Admin API

The Admin API allows you to list and revoke sessions for any user in your project. These endpoints require your API key.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

List sessions

Returns all active sessions for a user.

Query parameters

Response 200

{
  "data": [
    {
      "id": "sess_abc123",
      "user_id": "user_abc123",
      "created_at": "2025-01-10T08:30:00.000Z",
      "last_used_at": "2025-01-15T10:00:00.000Z",
      "expires_at": "2025-02-09T08:30:00.000Z",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0..."
    }
  ]
}

curl https://auth.example.com/api/v1/sessions?user_id=user_abc123 \
  -H "Authorization: Bearer your_api_key"

{
  "data": [
    {
      "id": "sess_abc123",
      "user_id": "user_abc123",
      "created_at": "2025-01-10T08:30:00.000Z",
      "last_used_at": "2025-01-15T10:00:00.000Z",
      "expires_at": "2025-02-09T08:30:00.000Z",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0..."
    }
  ]
}

Revoke a session

Revoke a specific session by its ID. The associated refresh token is invalidated immediately.

Response 200

{
  "success": true
}

Error responses

Configuration

Session duration is configurable per project in the AuthGate dashboard under Settings > Sessions.

Changing the session duration only affects new refresh tokens. Existing refresh tokens retain their original expiry.

SDK auto-handling

When using the @auth-gate/nextjs SDK, refresh tokens are managed automatically:

• The refresh token is stored in an httpOnly cookie (not accessible to client-side JavaScript)
• The SDK automatically refreshes the JWT before it expires
• On logout, the SDK revokes the refresh token and clears the cookie
• No client-side code is needed to handle token refresh

import { createAuthGate } from "@auth-gate/nextjs";

// The SDK handles refresh tokens automatically.
// No additional configuration is needed beyond the standard setup.
const auth = createAuthGate({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_URL!,
  appUrl: process.env.NEXT_PUBLIC_APP_URL!,
});