Sessions API

The Sessions API provides visibility and control over user sessions across the tenant. Administrators can list active sessions, revoke individual sessions, and configure session lifetime policies.

A session is created when a user successfully authenticates (via password, magic link, social login, or SSO). Each session tracks the device, IP address, last activity time, and authentication method used. Sessions remain active until they expire, are revoked by an administrator, or the user logs out.

Session Management

List Sessions

GET/api/admin/sessionsRequires: manage:sessions

List sessions across the tenant. Supports filtering by user ID and session status. Returns session metadata including device information, IP address, and authentication method. Sessions are ordered by last activity time descending. The response always includes aggregate stats for the tenant.

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 50)
`userId`	string	Filter sessions for a specific user
`status`	string	`active` for active sessions only, `revoked` for revoked sessions only

Success response

The response is a flat object — there is no ok wrapper. Sessions are under the top-level sessions key. Aggregate stats are always included.


{
  "sessions": [
    {
      "id": "clxyz123",
      "tenantId": "clt_abc",
      "userId": "clu_xyz789",
      "ipAddress": "203.0.113.50",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "device": "Chrome on macOS",
      "revoked": false,
      "createdAt": "2025-02-18T08:00:00Z",
      "updatedAt": "2025-02-18T09:45:00Z",
      "expiresAt": "2025-02-19T08:00:00Z",
      "user": {
        "email": "[email protected]",
        "firstName": "Alice",
        "lastName": "Smith"
      }
    },
    {
      "id": "cldef456",
      "tenantId": "clt_abc",
      "userId": "clu_abc123",
      "ipAddress": "198.51.100.42",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_3 like Mac OS X) AppleWebKit/605.1.15",
      "device": "Safari on iOS",
      "revoked": true,
      "createdAt": "2025-02-18T07:30:00Z",
      "updatedAt": "2025-02-18T09:30:00Z",
      "expiresAt": "2025-02-19T07:30:00Z",
      "user": {
        "email": "[email protected]",
        "firstName": "Bob",
        "lastName": "Jones"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  },
  "stats": {
    "active": 143,
    "last24h": 42
  }
}

Session object fields

The session object reflects the raw Prisma LoginSession model enriched with a nested user object:

Field	Description
`id`	Session identifier (cuid)
`tenantId`	Tenant this session belongs to
`userId`	ID of the authenticated user
`ipAddress`	Client IP at session creation
`userAgent`	Full user-agent string
`device`	Human-readable device label derived from user-agent
`revoked`	`true` if the session has been revoked
`createdAt`	When the session was created
`updatedAt`	Last update timestamp
`expiresAt`	When the session expires
`user.email`	User’s email address
`user.firstName`	User’s first name
`user.lastName`	User’s last name

stats object

Field	Description
`active`	Number of active (non-revoked, non-expired) sessions in the tenant
`last24h`	Number of sessions created in the last 24 hours

There is no separate /api/admin/sessions/stats endpoint — aggregate stats are returned inline with every list response.

Get Session

GET /api/admin/sessions/[id] is not yet implemented. Only the DELETE method exists on this route. Attempting a GET will return 405.

Revoke Session

DELETE/api/admin/sessions/[id]Requires: manage:sessions

Revoke a specific session. The associated refresh token is immediately invalidated. The access token continues to be valid until it expires naturally (JWTs are stateless). For immediate lockout, combine session revocation with short access token lifetimes.

Access tokens are JWTs and cannot be individually revoked without a blocklist. Auris relies on short access token lifetimes (default 15 minutes) for security. When a session is revoked, the refresh token is invalidated, so the user cannot obtain a new access token after the current one expires.

Success response


{
  "success": true
}

Error codes

Code	HTTP	Description
`NOT_FOUND`	404	Session does not exist

The API does not check whether a session is already revoked before updating it. Revoking an already-revoked session returns { "success": true } without error.

Revoke All User Sessions

POST /api/admin/sessions/revoke-all is not yet implemented. This route does not exist in the codebase.

Session Policies

Session policies control the lifetime of sessions and tokens across the tenant. These settings apply to all users unless overridden by application-specific configuration.

Get Security Settings

GET/api/realm-settingsRequires: admin:all

Retrieve the current session and security policy settings for the tenant.

Success response


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 86400,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 900,
    "maxConcurrentSessions": 5,
    "requireMfaForAdmin": true,
    "passwordMinLength": 8,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 5,
    "lockoutDuration": 900,
    "updatedAt": "2025-02-10T14:00:00Z"
  }
}

Session and token settings

Field	Type	Default	Description
`sessionMaxLifetime`	integer	`86400` (24h)	Maximum session duration in seconds, regardless of activity
`sessionIdleTimeout`	integer	`3600` (1h)	Session expires after this many seconds of inactivity
`refreshTokenExpiry`	integer	`604800` (7d)	Refresh token lifetime in seconds
`accessTokenExpiry`	integer	`900` (15m)	Access token lifetime in seconds
`maxConcurrentSessions`	integer	`5`	Maximum active sessions per user (0 = unlimited)

MFA settings

Field	Type	Default	Description
`requireMfaForAdmin`	boolean	`true`	Require 2FA for users with admin roles

Password policy settings

Field	Type	Default	Description
`passwordMinLength`	integer	`8`	Minimum password length
`passwordRequireUppercase`	boolean	`true`	Require at least one uppercase letter
`passwordRequireLowercase`	boolean	`true`	Require at least one lowercase letter
`passwordRequireNumbers`	boolean	`true`	Require at least one digit
`passwordRequireSpecial`	boolean	`false`	Require at least one special character
`passwordHistoryCount`	integer	`5`	Number of previous passwords to check against (0 = disabled)

Lockout settings

Field	Type	Default	Description
`lockoutThreshold`	integer	`5`	Number of failed login attempts before lockout
`lockoutDuration`	integer	`900` (15m)	Lockout duration in seconds

Update Security Settings

PUT/api/realm-settingsRequires: admin:all

Update session and security policy settings. The request body must use a sectioned envelope specifying which group of settings to update. Changes take effect for new sessions immediately. Existing sessions are not retroactively affected.

Request body

The body must include a section field identifying which settings group to update, and a data object with the fields for that section.


{
  "section": "tokens",
  "data": {
    "accessTokenExpiry": 600,
    "refreshTokenExpiry": 604800,
    "sessionMaxLifetime": 43200,
    "sessionIdleTimeout": 3600
  }
}

Supported section values

Section	Description
`tokens`	Access token, refresh token, and session lifetime settings
`login`	Login flow settings (MFA requirements, social login, etc.)
`bruteForce`	Lockout threshold, duration, and brute-force protection settings
`general`	General realm settings
`security`	Security policy settings (password policy, etc.)
`tokenClaims`	Custom claims to include in issued tokens

Success response

The response uses success (not ok) and returns the full nested realm settings object as returned by getRealmSettings():


{
  "success": true,
  "data": {
    "tokens": {
      "accessTokenExpiry": 600,
      "refreshTokenExpiry": 604800,
      "sessionMaxLifetime": 43200,
      "sessionIdleTimeout": 3600
    },
    "login": { "...": "..." },
    "bruteForce": { "...": "..." },
    "general": { "...": "..." },
    "security": { "...": "..." },
    "tokenClaims": { "...": "..." }
  }
}

Error codes

Code	HTTP	Description
`VALIDATION_ERROR`	400	Invalid section name or invalid value within the data object

Validation rules

accessTokenExpiry must be between 60 (1 minute) and 86400 (24 hours)
refreshTokenExpiry must be between 3600 (1 hour) and 2592000 (30 days)
sessionMaxLifetime must be >= accessTokenExpiry
sessionIdleTimeout must be <= sessionMaxLifetime
maxConcurrentSessions must be between 0 and 100
passwordMinLength must be between 6 and 128
lockoutThreshold must be between 1 and 100
lockoutDuration must be between 60 (1 minute) and 86400 (24 hours)

Setting very short access token lifetimes (under 5 minutes) increases the frequency of token refresh requests. Setting very long lifetimes reduces security. The recommended range is 5 to 30 minutes.

Concurrent Session Enforcement

When maxConcurrentSessions is set to a non-zero value, Auris enforces a limit on the number of active sessions per user. When a new session is created and the user already has the maximum number of sessions:

The oldest session (by createdAt) is automatically revoked.
The new session is created normally.
The user receives a notification that an older session was terminated (if in-app notifications are enabled).

This behavior ensures that users are never prevented from logging in due to stale sessions, while still maintaining a reasonable cap on concurrent access.

Session Lifecycle


User authenticates
       |
       v
  Session created (revoked: false)
       |
       +--- User makes API requests ---> updatedAt refreshed
       |
       +--- Access token expires ---> User refreshes token
       |         (refreshToken still valid)
       |
       +--- Idle timeout reached ---> Session expired
       |
       +--- Max lifetime reached ---> Session expired
       |
       +--- Admin revokes session ---> Session revoked
       |
       +--- User logs out ---> Session revoked
       |
       v
  Session inactive (revoked: true)

Permissions Reference

Permission	Description
`manage:sessions`	List and revoke sessions across the tenant
`admin:all`	View and update session policies and security settings

Individual users can view and revoke their own sessions through the user profile endpoints (GET /api/user/security/sessions, DELETE /api/user/security/sessions/[id]) without needing admin permissions. The endpoints documented on this page are for tenant-wide administration.

Sessions & Token Rotation — How sessions, tokens, and rotation work together
Session Management Guide — Configure session policies and enforcement
Session Management — Monitor and revoke sessions from the Console
Authentication API — Login and token endpoints that create sessions

Sessions API

Session Management

List Sessions

Get Session

Revoke Session

Revoke All User Sessions

Session Policies

Get Security Settings

Update Security Settings

Concurrent Session Enforcement

Session Lifecycle

Permissions Reference

Related