Auth Docs

Overview

This API uses Bearer Token authentication. Every request to a protected endpoint must include an Authorization header with a valid token.

GET /auth/token returns a JWT for registered users.

Token Types
  • Access Token – short‑lived (15 min) token for API calls.
  • Refresh Token – long‑lived (30 days) token used to obtain new access tokens.

Both tokens are signed with HS256 and contain the user ID, roles, and expiration.

Endpoints

Login

POST /auth/login
Headers:
  Content-Type: application/json

Body:
{
  "username": "user@example.com",
  "password": "your_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
}

Refresh Token

POST /auth/refresh
Headers:
  Content-Type: application/json

Body:
{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
}

Response includes a new access_token.

Error Handling
  • 401 Unauthorized – Invalid or missing token.
  • 403 Forbidden – Token valid but lacks required scope.
  • 400 Bad Request – Malformed request payload.

Error response format:

{
  "error": "Invalid credentials",
  "code": 401
}
FAQ

Q: How long does an access token last?
A: 15 minutes. Use the refresh token to extend the session.

Q: Can I revoke a refresh token?
A: Yes, call POST /auth/revoke with the refresh token.