Control CoreDocs

Session Management

Audience: Administrators, Platform Engineers
Time: ~15 min
Prerequisites: Control Plane deployed; access to API environment configuration

Control Plane sessions combine short-lived access JWTs with server-side session records so operators can be logged out centrally and compliance requirements for idle timeout are met.

How sessions work

  1. Successful login (password, SSO, or passkey) creates a UserSession row with unique jti (JWT ID).
  2. The access token includes jti, sub, exp, and iat; signed with RS256 by default (GET /auth/jwks.json for verifiers).
  3. Every API call validates the JWT and checks the session row is not revoked or expired.

Revoked or expired sessions return HTTP 401 with X-Session-Status: revoked when applicable.

Token lifetime

SettingDefaultNotes
Access token30 minutesJWT_ACCESS_TOKEN_EXPIRE_MINUTES / ACCESS_TOKEN_EXPIRE_MINUTES
Recommended access token lifetime15 minutesShorter JWT + opaque refresh rotation

Troubleshooting: If users report unexpected logouts, check access token expiry and idle timeout settings. If API returns Session has been revoked, an administrator or policy ended the session — sign in again.

Idle and absolute timeout

Configure under Settings → General → Security:

  • Session timeout (minutes) — idle warning and logout (default 60, range 5–480).
  • CONTROL_CORE_SESSION_MAX_ABSOLUTE_HOURS — maximum uninterrupted session (default 8 hours).
  • CONTROL_CORE_SESSION_MAX_CONCURRENT — cap simultaneous sessions per user (when documented for your release).

The UI shows a countdown warning before idle logout; Stay Logged In refreshes the token when the server validates activity.

Troubleshooting: If idle warnings appear during active use, test with a clean browser profile (extensions can block activity signals). After changing timeout minutes, save in General Settings and reload the Control Plane UI.

Revocation

Sessions are revoked when:

  • User signs out
  • Administrator deactivates the user
  • Password reset or security event (target: under 100ms propagation via the Redis revocation bus)
  • Token refresh rotates the prior jti

Dual-token refresh stores refresh_token_hash on the session row — opaque refresh tokens are never persisted in plaintext.

Signing key rotation

Administrators can rotate JWT signing keys via POST /auth/keys/rotate. Existing sessions remain valid until expiry or explicit revoke — rotation alone does not mass-logout users.

Troubleshooting: After rotation, external verifiers must refresh JWKS from GET /auth/jwks.json. If third-party integrations fail validation, confirm they cache JWKS for less than your rotation interval.

Next steps