Session and token behavior
Authentication produces two tokens that together manage session lifecycle and API authorization.
- Access token
-
A short-lived ES256 JWT (default: 15 minutes) that authorizes API requests. Automation orchestrator validates the JWT signature with the public key. It then checks the token version against the database to confirm the token is current. The token contains claims for user identity, group memberships, and authentication metadata.
- Refresh token
-
A longer-lived ES256 JWT (default: 8 hours) stored as an
ao_refresh_tokenHttpOnly cookie. Automation orchestrator persists refresh sessions in the PostgreSQL database. Automation orchestrator does not rotate the refresh token. It remains valid for its full lifetime. When the access token expires, the client uses the refresh token to obtain a new access token. Automation orchestrator refreshes group memberships from the database on each token refresh.
The refresh token acts as a hard session boundary. When it expires, the user must re-authenticate.
The 15-minute lifetime is the maximum age of an access token, not a guaranteed validity window. Automation orchestrator can invalidate an access token before it expires. The following events invalidate an access token on its next request, typically within 5 seconds:
- Logging out
- Disabling a user account
- Changing a user's permissions
The response depends on the event:
- A disabled user receives a
401 ACCOUNT_DISABLEDerror. - A user whose permissions changed receives a
401 TOKEN_STALEerror. The client must refresh the token to continue.
Automation orchestrator exempts the /api/v1/auth/logout and /api/v1/auth/refresh endpoints from these checks so that clients can complete logout and obtain a new token.