Session Management

Manage active sessions across users, organizations, and devices. Auth: Authorization: Bearer <jwt> (admin scope for org-wide operations).

Endpoints

GET /api/organizations/:org_uuid/session-inventory

List all active sessions for an org. Query: user_uuid?, device_uuid?, limit?, offset?.

Output: ~~~json { "data": [{ "session_id": "sess-uuid", "user_uuid": "user-uuid", "device_uuid": "device-uuid", "created_at": "2026-05-11T09:00:00Z", "last_seen_at": "2026-05-11T10:00:00Z", "ip_address": "1.2.3.4", "user_agent": "Mozilla/5.0..." }], "total": 42 } ~~~

DELETE /api/organizations/:org_uuid/session-inventory/:session_id

Revoke a specific session. Adds JWT jti to Redis revocation list. Returns 204.

DELETE /api/organizations/:org_uuid/session-inventory

Bulk revoke all sessions for an org. Body: { "exclude_current": true }. Requires step-up auth. Response: { "revoked": 41 }.

GET /api/devices/:device_uuid/session-inventory

List sessions for a specific device. Same response shape.

DELETE /api/devices/:device_uuid/session-inventory/:session_id

Revoke a device session. Returns 204.

POST /api/auth/logout

Self-service logout. Revokes current JWT. No body required. Returns 204.

GET /api/auth/sessions

List the authenticated user's own sessions across all devices.

Output: ~~~json { "data": [{ "session_id": "sess-uuid", "device_uuid": "dev-uuid", "created_at": "...", "last_seen_at": "...", "current": true }] } ~~~

Endpoint Summary

| Method | Path | Purpose | |---|---|---| | GET | /api/organizations/{org}/session-inventory | List org sessions | | DELETE | /api/organizations/{org}/session-inventory/{id} | Revoke one session | | DELETE | /api/organizations/{org}/session-inventory | Bulk revoke (step-up) | | POST | /api/organizations/{org}/revoke-all-sessions | Revoke all org sessions | | GET | /api/devices/{device}/session-inventory | List device sessions | | DELETE | /api/devices/{device}/session-inventory/{id} | Revoke device session | | POST | /api/devices/{device}/revoke-all | Revoke all device sessions | | GET | /api/devices/{device}/accounts | List device accounts | | POST | /api/devices/{device}/accounts | Add device account | | DELETE | /api/devices/{device}/accounts/{id} | Remove device account | | POST | /api/devices/{device}/active-account | Switch active account | | POST | /api/auth/logout | Self-service logout | | GET | /api/auth/sessions | List own sessions |

SDK Examples

Python

~~~python

Org session inventory

sessions = client.org_session_inventory("org-uuid")

Revoke all org sessions

client.org_revoke_all_sessions("org-uuid")

Device management

accounts = client.list_device_accounts("device-uuid") client.add_device_account("device-uuid", {"email": "user@example.com", "org_name": "Acme"}) client.switch_device_active_account("device-uuid", "account-uuid")

Device sessions

device_sessions = client.device_session_inventory("device-uuid") client.revoke_all_device_sessions("device-uuid") ~~~

Node.js / TypeScript

~~~typescript // Org session inventory const sessions = await client.orgSessionInventory('org-uuid');

// Revoke all org sessions await client.orgRevokeAllSessions('org-uuid');

// Device management const accounts = await client.listDeviceAccounts('device-uuid'); await client.addDeviceAccount('device-uuid', { email: 'user@example.com' }); await client.switchDeviceActiveAccount('device-uuid', 'account-uuid'); ~~~

Go

~~~go // Org session inventory sessions, err := client.OrgSessionInventory(ctx, "org-uuid")

// Revoke all org sessions _, err = client.OrgRevokeAllSessions(ctx, "org-uuid")

// Device management accounts, err := client.ListDeviceAccounts(ctx, "device-uuid") _, err = client.SwitchDeviceActiveAccount(ctx, "device-uuid", "account-uuid") ~~~

Rust

~~~rust // Org session inventory let sessions = client.org_session_inventory("org-uuid").await?;

// Revoke all org sessions client.org_revoke_all_sessions("org-uuid").await?;

// Device management let accounts = client.list_device_accounts("device-uuid").await?; client.switch_device_active_account("device-uuid", "account-uuid").await?;

// Device sessions let dev_sessions = client.device_session_inventory("device-uuid").await?; client.revoke_all_device_sessions("device-uuid").await?; ~~~

Revocation Mechanism

JWTs are revoked by adding their jti to revoked-jti:<jti> in Redis. Auth middleware checks this on every request — revocation takes effect within milliseconds.

Error Reference

| Status | Code | Meaning | |---|---|---| | 400 | invalid_uuid | Malformed UUID in path | | 403 | forbidden | Admin scope required for org-wide ops | | 403 | step_up_required | Bulk revocation requires elevated token | | 404 | not_found | Session does not exist | | 409 | already_revoked | Session already revoked |