Sessions

Manage active user sessions across devices. Each login creates a session that tracks the device, IP address, and last activity. Users can view all their active sessions and revoke any session individually.

The session model

Properties

Name
id
Type
string
Description
Unique identifier for the session.
Name
ip_address
Type
string
Description
The IP address from which the session was created.
Name
user_agent
Type
string
Description
The User-Agent string of the client that created the session (browser, OS, device info).
Name
last_active_at
Type
string
Description
ISO 8601 timestamp of the last activity on this session.
Name
is_current
Type
boolean
Description
Whether this session corresponds to the token being used in the current request.
Name
created_at
Type
string
Description
ISO 8601 timestamp of when the session was created (i.e., when the user logged in on this device).

GET/auth/api/v1/auth/sessions

List active sessions

Retrieve all active sessions for the authenticated user. Each session includes device information, IP address, and whether it is the current session. Use this to let users audit their active sessions and identify any unauthorized access.

Request

GET

/auth/api/v1/auth/sessions

curl https://your-sphere.example.com/auth/api/v1/auth/sessions \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": [
    {
      "id": "9c8b7a6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "ip_address": "192.168.1.42",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
      "last_active_at": "2026-02-24T14:32:00Z",
      "is_current": true,
      "created_at": "2026-02-24T08:15:00Z"
    },
    {
      "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "ip_address": "10.0.0.15",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3 Mobile/15E148 Safari/604.1",
      "last_active_at": "2026-02-24T12:05:00Z",
      "is_current": false,
      "created_at": "2026-02-23T19:45:00Z"
    },
    {
      "id": "f6e5d4c3-b2a1-0f9e-8d7c-6b5a4f3e2d1c",
      "ip_address": "203.0.113.50",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
      "last_active_at": "2026-02-23T16:20:00Z",
      "is_current": false,
      "created_at": "2026-02-22T09:30:00Z"
    }
  ]
}

DELETE/auth/api/v1/auth/sessions/{id}

Revoke a session

Revoke a specific session by its ID. This immediately invalidates all tokens associated with that session. You cannot revoke the current session using this endpoint -- use the logout endpoint instead.

URL parameters

Name
id
Type
string
Description
The unique identifier of the session to revoke.

Request

DELETE

/auth/api/v1/auth/sessions/{id}

curl -X DELETE https://your-sphere.example.com/auth/api/v1/auth/sessions/a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (204 No Content)

// No response body

Session lockout

Sphere enforces account lockout after repeated failed login attempts to protect against brute-force attacks.

When a user exceeds the maximum number of failed login attempts (configurable, default: 5), the account is temporarily locked for a configurable duration (default: 15 minutes). During the lockout period, all login attempts for that account will be rejected with a 429 status code, regardless of whether the credentials are correct.

The lockout policy can be retrieved from the auth config endpoint.

Lockout behavior

Name
max_attempts
Type
integer
Description
Maximum number of consecutive failed login attempts before the account is locked. Default: 5.
Name
lockout_duration
Type
integer
Description
Duration of the lockout in seconds. Default: 900 (15 minutes).
Name
remaining_attempts
Type
integer
Description
Returned in the 429 error response, indicating how many seconds until the lockout expires.

Lockout error response (429)

{
  "message": "Too many login attempts. Please try again in 847 seconds.",
  "errors": {
    "login": [
      "Too many login attempts. Please try again later."
    ]
  },
  "retry_after": 847
}