Token lifecycle
How access and refresh tokens work in AISquare and how to manage them in production.
AISquare supports a token-based authentication flow built on access tokens and refresh tokens. Tokens let you authenticate users without resending the API key on every request. This page covers the flow, how to refresh safely, and how to handle failures in a production system.
Token types
| Token | Purpose | Expiry |
|---|---|---|
| Access token | Authenticates API requests | 7 days |
| Refresh token | Generates new access tokens | 30 days |
The flow
API key -> login -> access token + refresh token
|
use access token for requests
|
access token expires
|
use refresh token to get a new access tokenObtain tokens
Call the login endpoint with the user's API key. You receive an access token and a refresh token.
Use the access token
Send the access token on every authenticated request.
Authorization: Bearer <access_token>Handle expiration
The access token expires after 7 days. When a request fails with an authentication error, detect it and trigger a refresh.
Refresh the token
Use the refresh token to mint a new access token, then replace the expired one.
refresh_token -> new access_tokenWhere to manage tokens
Manage tokens on the backend
Store and refresh tokens on your server, not in the browser. A backend keeps credentials out of client code, centralizes refresh logic, and avoids token leakage. See Integration patterns.
A backend-managed flow looks like this:
user request
|
backend checks token validity
|
if expired -> refresh token
|
call AISquare APIStoring tokens in a frontend app risks leakage, makes refresh hard to coordinate, and widens your attack surface. Avoid it.
Refresh strategies
Pick the strategy that matches how long your sessions run.
-
Reactive. Make the request; if it fails on expiry, refresh and retry. Simple, and fine for low-traffic paths.
-
Proactive. Track the expiry time and refresh just before it lapses.
if current_time > expiry_time - buffer: refresh token -
Background. Refresh on a schedule so long-running sessions never block on a refresh.
Handling failures
| Situation | What to do |
|---|---|
| Access token expired | Refresh with the refresh token, then retry. |
| Refresh token expired | Re-authenticate with the API key to get new tokens. |
| Invalid token | Clear stored tokens and restart the flow. |
See Errors for the status codes behind these cases.
Storage best practices
-
Store securely. Use encrypted storage; never keep tokens in plain text.
-
Associate with the user. Keep tokens keyed to your user ID.
user_id -> access_token + refresh_token -
Rotate safely. Replace old tokens immediately after a refresh and never reuse a stale one.
API key or tokens
| Scenario | Recommended |
|---|---|
| Simple backend calls | API key |
| User sessions | Access and refresh tokens |
| Long-running apps | Tokens with refresh |
Putting it together
- Register the user and get an API key.
- Log in to get tokens.
- Use the access token for requests.
- Refresh when it expires.
- Repeat.