Sessions and tokens

This page explains the token lifecycle for custom integrations. The built-in frontend handles refresh and session handoff for you. In your components, use authenticated requests instead of managing tokens.

Two tokens per session

Authentication is JWT-based, with two tokens per session:

• The access token travels as the Authorization: Bearer header on authenticated API requests. Its default lifetime is 1 hour. It carries the user id, the active tenantId, and the session id. Logging out or revoking a device deletes its session row, so its access token stops working on the next request, not when it expires.
• The refresh token belongs to a session row, one per device and login. The row records the user agent, browser, OS, IP, and last activity. The refresh token's default lifetime is 30 days. A refresh exchanges it for a new access token, and also rotates the refresh token once it is older than 15 days.

One signing key per user

The DMS signs tokens with a per-user secret, derived from the configured jwtSecret and a rotating per-user key. Rotating that key invalidates every outstanding token of the user at once. A password reset rotates it and signs out every device. DELETE /dms/pages/settings/user/security/other-sessions rotates it and signs out every device but the caller's.

A password change and the Security page's Sign out other sessions both rotate the key and delete the other sessions, so those devices lose access immediately. The device that asked stays signed in. The response carries a sessionHandoff, a single-use token valid 60 seconds that the DMS stores in the refresh slot of that session. The frontend exchanges it at /api/auth/session-handoff, through the frontend server's /auth/establish, for a new token pair for the same session. The DMS declares that endpoint.

Revoking sessions

Users can inspect and revoke individual sessions on the Security page. The frontend refreshes expired access tokens without user action. A revoked or invalid session still requires the user to sign in again.

Revoke another session

The Sessions section of the Security page marks the current session This device and lists every other sign-in of the account. Each other session has its own Sign out action, which revokes that session alone. The current session has none. A request from a revoked session answers 401, and the user signs in again there.