Sessions — Core API

Lists all sessions for a user.

Sessions represent authenticated contexts for a user. Each session tracks:

• Status - Current state (active, suspended, revoked, expired)
• Device info - User agent, IP address, device fingerprint
• Tokens - Associated access and refresh tokens
• Activity - Last activity timestamp

Session statuses:

• inactive - Session created but not yet activated (pre-token issuance)
• active - Normal operational state
• suspended - Temporarily blocked by admin (can be reactivated)
• revoked - Permanently terminated (logout or security action)
• expired - Session lifetime exceeded

Use this endpoint to:

• Show users their active sessions
• Identify suspicious sessions for security review
• Audit session history

Retrieves detailed information about a specific session.

Returns complete session data including:

• User info - The user ID associated with this session
• Client info - The OAuth client that initiated the session
• Device context - User agent, IP address, device fingerprint
• Timestamps - Created, last activity, expiration times
• Token metadata - Current access/refresh token JTIs (not the tokens themselves)

Use this endpoint to:

• Investigate suspicious activity
• Verify session validity before sensitive operations
• Get context for security audit logs

Permanently revokes a session.

Revoking a session immediately:

• Invalidates all tokens associated with the session
• Prevents any further token refresh attempts
• Logs the user out of this session
• Revokes linked RP/client sessions when the target is an OP/SSO session
• Emits session.terminated events and OIDC backchannel logout per affected client session

Revocation reasons: Include a reason in the request body for audit purposes — one of: user_logout, admin_action, security_event, password_changed, inactivity, token_compromised, other.

Pass revoke_all_user_sessions: true to revoke every non-terminal session belonging to this session's user ("log out everywhere"), including active, suspended, and not-yet-activated inactive sessions.

Important: This action is permanent. To temporarily block a session while investigating, use Suspend Session instead.

Temporarily suspends a session.

Use suspension when you need to block access while investigating suspicious activity, without permanently revoking the session.

When suspended:

• All tokens immediately become invalid
• Token refresh attempts fail
• The session can be reactivated later

Use cases:

• Detected unusual activity requiring investigation
• User reports possible account compromise
• Temporary administrative hold

Difference from revoke:

• Suspended sessions can be reactivated
• Revoked sessions are permanently terminated

Include a reason in the request body for audit purposes.

Reactivates a previously suspended session.

After investigation confirms the session is legitimate, use this endpoint to restore access.

When reactivated:

• Session status returns to active
• Tokens become valid again (if not expired)
• User regains access without re-authenticating

Limitations:

• Only suspended sessions can be reactivated
• Revoked or expired sessions cannot be reactivated
• The user must obtain new tokens via refresh if their previous tokens expired during suspension