EndUser Session Management

Overview

The EndUser Session Management API provides endpoints for managing end user active sessions. You can list sessions, revoke individual sessions, or revoke all sessions for a user.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/sessions`	List sessions
GET	`/api/admin/sessions/:id`	Get session details
DELETE	`/api/admin/sessions/:id`	Revoke session
POST	`/api/admin/users/:id/logout`	Revoke all user sessions
POST	`/api/admin/sessions/revoke-all`	Revoke all sessions

List Sessions

Retrieve a list of active sessions within the tenant.

Endpoint

GET /api/admin/sessions

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 20, max: 100)
`cursor`	string	-	Pagination cursor
`user_id`	string	-	Filter by specific user
`client_id`	string	-	Filter by specific client
`active_only`	boolean	-	Active sessions only (default: true)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/sessions?user_id=usr_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "sess_xyz789",
      "user_id": "usr_abc123",
      "client_id": "client_def456",
      "client_name": "My Web App",
      "ip_address": "203.0.113.1",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "device_info": {
        "type": "desktop",
        "os": "macOS",
        "browser": "Chrome"
      },
      "location": {
        "country": "US",
        "city": "New York"
      },
      "created_at": 1705881600,
      "last_activity_at": 1706054400,
      "expires_at": 1706486400
    }
  ],
  "total": 3,
  "cursor": null
}

Get Session Details

Retrieve detailed information for a specified session.

Endpoint

GET /api/admin/sessions/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Session ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/sessions/sess_xyz789" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "sess_xyz789",
  "user_id": "usr_abc123",
  "user_email": "[email protected]",
  "user_name": "John Doe",
  "client_id": "client_def456",
  "client_name": "My Web App",
  "ip_address": "203.0.113.1",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "device_info": {
    "type": "desktop",
    "os": "macOS",
    "os_version": "10.15.7",
    "browser": "Chrome",
    "browser_version": "120.0.0"
  },
  "location": {
    "country": "US",
    "country_name": "United States",
    "region": "New York",
    "city": "New York",
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "auth_method": "password",
  "mfa_verified": true,
  "scopes": ["openid", "profile", "email"],
  "created_at": 1705881600,
  "last_activity_at": 1706054400,
  "expires_at": 1706486400
}

Revoke Session

Revoke a specified session.

Endpoint

DELETE /api/admin/sessions/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Session ID

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/sessions/sess_xyz789" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)

Revoke All User Sessions

Revoke all active sessions for a specified user. Used for forced logout.

Endpoint

POST /api/admin/users/:id/logout

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	User ID

Request Body

Field	Type	Required	Description
`reason`	string	-	Logout reason

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/logout" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Forced logout due to password change"
  }'

Response Example

{
  "user_id": "usr_abc123",
  "revoked_sessions": 3,
  "revoked_at": 1706140800
}

Revoke All Sessions

Revoke all active sessions within the tenant. Used for emergency security response.

Endpoint

POST /api/admin/sessions/revoke-all

Request Body

Field	Type	Required	Description
`reason`	string	✓	Revocation reason (for audit log)
`exclude_admin`	boolean	-	Exclude admin sessions (default: false)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/sessions/revoke-all" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security incident response",
    "exclude_admin": true
  }'

Response Example

{
  "revoked_sessions": 1250,
  "revoked_at": 1706227200,
  "excluded_admin_sessions": 5
}

Session Expiration

Session expiration is managed by tenant settings. Default values:

Setting	Default Value	Description
`session_lifetime`	86400 seconds (24 hours)	Maximum session lifetime
`idle_timeout`	3600 seconds (1 hour)	Idle timeout
`absolute_timeout`	604800 seconds (7 days)	Absolute timeout

These settings can be changed via the Settings Management API.