API Authentication

Intotes uses JWT tokens delivered as HTTP-only cookies for authentication.

Token Types

Token	Cookie Name	TTL	Purpose
Access token	access_token	20 minutes	Authenticate API requests
Refresh token	refresh_token	72 hours	Obtain new access tokens

How It Works

1. Sign in via POST /api/v1/auth/sign-in (or sign-up, OAuth)
2. Server sets access_token and refresh_token as HTTP-only cookies
3. Cookies are sent automatically with every request — no manual header needed
4. When the access token expires, call POST /api/v1/auth/refresh to get a new one

Using Bearer Token

For programmatic clients that don't support cookies, you can pass the token manually:

Authorization: Bearer <access_token>

The Partner Integration endpoints are the exception: they authenticate with the X-Partner-Key header instead of a user token.

Auth Levels

Each endpoint documents its required auth level:

Level	Description
None	Public endpoint, no authentication needed
Optional	Works with or without auth (may return different data)
Required	Must be authenticated
Creator	Must have is_creator role
StatsViewer	Must have is_stats_viewer role (admin endpoints)

Refresh Flow

# When access token expires (401 response), refresh it:
curl -X POST https://intotes.com/api/v1/auth/refresh \
  --cookie "refresh_token=<your_refresh_token>"

The server responds with a new access_token cookie and the current user info.

Logout

curl -X DELETE https://intotes.com/api/v1/auth/logout \
  --cookie "access_token=<token>"

Both tokens are invalidated and cookies are cleared.