Authentication
Yoyo Market (hereinafter “Yoyo”) 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.