Authentication
Intotes uses JWT-based authentication with short-lived access tokens and longer-lived refresh tokens. Tokens are delivered as HTTP-only cookies and can also be sent via the Authorization header.
Token Lifecycle​
| Token | TTL | Purpose |
|---|---|---|
access_token | 20 minutes | Authorizes API requests. Sent as an HTTP-only cookie or as a Bearer token in the Authorization header. |
refresh_token | 72 hours | Used to obtain a new access token when the current one expires. Sent as an HTTP-only cookie. |
Both tokens are set automatically as HTTP-only cookies upon successful sign-in or OAuth callback.
Sending Authenticated Requests​
Include the access token in every request that requires authentication. The platform accepts it in two ways:
- Cookie (automatic) -- if you authenticated through the browser, cookies are sent automatically.
- Authorization header (explicit):
Authorization: Bearer <access_token>
Refreshing Tokens​
When your access token expires, call the refresh endpoint to obtain a new pair:
POST /api/v1/auth/refresh
No request body is required. The refresh token is read from the HTTP-only cookie. On success, the server sets new access_token and refresh_token cookies in the response.
If the refresh token itself has expired (after 72 hours of inactivity), you must sign in again.
Optional Authentication​
Some endpoints support optional authentication. They work for both authenticated and unauthenticated users, but return different or enriched content when a valid token is present.
For example, an event listing endpoint may include your personal watchlist status and positions when you are authenticated, but still return the base event data without a token.
Logging Out​
To end your session and invalidate tokens:
DELETE /api/v1/auth/logout
This clears the authentication cookies and invalidates the refresh token on the server side. After logging out, you must sign in again to access protected endpoints.
Security Notes​
- Access tokens are intentionally short-lived (20 minutes) to limit exposure if compromised.
- Refresh tokens are stored as HTTP-only cookies, making them inaccessible to client-side JavaScript and resistant to XSS attacks.
- Always use HTTPS in production to protect tokens in transit.