Authentication

Auth model

• Access token: short-lived JWT used for protected API calls
• Refresh token: long-lived token used to get new access tokens
• Send access token as Bearer header on protected endpoints

Bearer header format

Authorization: Bearer <access_token>

Token lifecycle endpoints

POST /auth/register

Creates a user account.

POST /auth/login

Returns:

{
  "access_token": "<jwt>",
  "refresh_token": "<jwt>",
  "user_id": "<uuid>",
  "tier": "Free",
  "expires_in": 3600
}

POST /auth/refresh

Use refresh token to rotate and receive fresh tokens:

{
  "refresh_token": "<jwt>"
}

POST /auth/logout

Ends the refresh token session represented by the provided refresh token.

Password reset endpoints

• POST /auth/request-password-reset
• GET /auth/verify-reset-token?token=<token>
• POST /auth/reset-password
• GET /reset-password (browser reset page)

Common auth failures

• 401 Unauthorized: missing/invalid token or invalid credentials
• 400 Bad Request: missing required auth fields