Refresh Tokens
Understand how refresh tokens work and how sessions are maintained.
Refresh tokens are used to maintain user sessions without requiring frequent re-authentication.
In Tzylo Auth CE, refresh tokens are handled entirely by the server and are not exposed to client-side JavaScript.
Purpose of refresh tokens
Access tokens are intentionally short-lived. Refresh tokens allow clients to request new access tokens when they expire.
- Reduce the need for repeated logins
- Limit the lifetime of exposed access tokens
- Support long-lived user sessions
Storage mechanism
Refresh tokens are stored as HTTP-only cookies.
- Not accessible via JavaScript
- Automatically sent with requests
- Protected from most XSS attacks
Cookie behavior can be controlled using environment variables such as COOKIE_SECRET and COOKIE_SAME_SITE .
Refresh flow
The refresh process follows a simple request-response flow:
- Client sends a request to
POST /refresh - Server reads the refresh token from the cookie
- Token validity is verified
- A new access token is issued
POST /refreshExpiration and rotation
Refresh tokens have a longer lifetime than access tokens and eventually expire.
When a refresh token expires:
- The session becomes invalid
- The user must log in again
Token lifetimes are configurable using environment variables.
Logout behavior
When a user logs out:
- The refresh token is invalidated server-side
- The cookie is cleared
- Further refresh attempts are rejected
Security notes
- Refresh tokens should never be stored manually by clients
- Always use HTTPS in production
- Configure proper cookie policies for cross-site usage