Token Refresh¶
Access tokens have a limited lifetime. Use the refresh token to obtain a new access token without requiring the user to log in again.
Request¶
Requires a valid refresh_token_cookie. The CSRF header for this request must use the refresh CSRF token.
POST /api/token-refresh HTTP/1.1
Host: acme.knosc.com
Cookie: refresh_token_cookie=<refresh-jwt>
X-XSRF-TOKEN: <value-of-csrf_refresh_token-cookie>
Response¶
HTTP/1.1 200 OK
Set-Cookie: access_token_cookie=<new-jwt>; HttpOnly; SameSite=Lax; Path=/
Set-Cookie: csrf_access_token=<new-csrf-token>; SameSite=Lax; Path=/
The new csrf_access_token cookie must be used for all subsequent state-modifying requests.
Token Invalidation¶
Tokens are automatically invalidated when the associated user account is modified (password change, role change, account suspension). The token carries a last_modified_at claim validated on every request - no explicit blocklist is maintained.
Code Example¶
def refresh_session(session: requests.Session, base_url: str) -> bool:
"""Returns True if token was refreshed successfully."""
csrf = session.cookies.get("csrf_refresh_token")
r = session.post(
f"{base_url}/api/token-refresh",
headers={"X-XSRF-TOKEN": csrf}
)
return r.status_code == 200