Refresh Session

Initial sign-in JWT is for a maximum duration of 1h. Need to refresh to avoid session expiration.

How it works:

Send the refresh_token received during Sign-in or Sign-up to this endpoint to obtain a new access_token (and a new refresh_token).

The access_token is short-lived (≈1h) and must be refreshed before expiration to avoid session expiration.

Token lifecycle & refresh strategy:

• Access token (`access_token`): expires after 3600 seconds (1 hour), as indicated by the expires_in field in the response.
• Refresh token (`refresh_token`): valid for 24 hours but is single-use — once consumed by this endpoint it is immediately revoked and a new one is returned.
• Recommended refresh cadence: proactively refresh 5–10 minutes before the access token expires (i.e. at ~50–55 min after issuance). This avoids race conditions where an in-flight request hits a just-expired token.
• Late refresh: if the access token has already expired but the refresh token is still valid (< 24 h old), calling this endpoint will still succeed and return a fresh pair of tokens.
• Expired refresh token: if the refresh token itself has expired (> 24 h), this endpoint returns 401 Unauthorized. The user must re-authenticate via Sign-in or Sign-up.
• One-time use: each refresh_token can only be used once. Always store and use the latest refresh_token returned by the most recent call. Replaying an already-consumed refresh token returns 401 Unauthorized.

For AI agents / automated integrations:

Schedule a token refresh timer based on expires_in (e.g. setTimeout(refresh, (expires_in - 300) * 1000)). On WebSocket connections, listen for error_code: 'TOKEN_EXPIRED' to trigger an immediate refresh.

Request body parameters:

• refresh_token (string, required): Refresh token (JWT) issued at sign-in or sign-up

Response structure (200 OK):

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "issuer": "foo.domain",
  "audience": "foo.domain",
  "subject": "<externalUserId>",
  "roles": ["USER"]
}