Access tokens are short-lived and once the access token expires, the refresh token can be used to retrieve a new access token. The refresh tokens are used for offline access, i.e., when the user is no longer actively interacting with an app but the app continues operating.
By default, access tokens expire after 1 hour, while refresh tokens expire after 2 weeks. The maximum period of time the token can be rotated is also 2 weeks, by default. Once expired, refresh tokens cannot be used to retrieve new access and ID tokens. Default expirations can be customized in the client settings. Alternatively, you can create resources that allow shorter or longer token lifespan.
Refresh tokens are always returned along with other tokens in backend authentication flows and Mosaic redirect-based flows, such as email magic link and SMS OTP.
In pure OIDC integrations, refresh tokens must be requested explicitly. The oidc/auth request must include scope set to offline_access and prompt set to consent. Since refresh tokens are rotated upon each use, a new refresh token is returned too.
When you exchange a refresh token for a new access token, Mosaic preserves the custom claims from the original token. The refreshed token keeps the same enriched claims and claim placement as the token issued during authentication.
This applies across all supported enrichment patterns:
- Tokens enriched with Enrich SSO Token
- Tokens enriched with Enrich Access and ID Token
- Claims stored under
custom_claims - Claims added at the token root (
placement: root) - Backend-based authentication flows
- OIDC-based authentication flows
For example, if a journey enriches an access token during authentication and the app later refreshes that token, the new access token will still contain the same custom claims.
This behavior ensures that refreshed tokens do not lose:
- Claims stored under
custom_claims - Claims added at the token root
- Token enrichment applied during authentication