Endpoints

POST /api/v1/auth/login

Authenticate a user and return JWT tokens.

Request Body:

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Response (401 Unauthorized):

{
  "detail": "Invalid credentials"
}

POST /api/v1/auth/refresh

Refresh an access token using a refresh token.

Request Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

GET /api/v1/auth/me

Get current user information.

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "id": 123,
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "created_at": "2024-01-01T00:00:00Z"
}

Request/Response Examples

Example: Complete Login Flow

import requests

# 1. Login
login_response = requests.post(
    "http://localhost:8000/api/v1/auth/login",
    json={
        "email": "user@example.com",
        "password": "secure_password"
    }
)
tokens = login_response.json()

# 2. Use access token
headers = {"Authorization": f"Bearer {tokens['access_token']}"}
user_response = requests.get(
    "http://localhost:8000/api/v1/auth/me",
    headers=headers
)
user_data = user_response.json()

# 3. Refresh token when needed
refresh_response = requests.post(
    "http://localhost:8000/api/v1/auth/refresh",
    json={"refresh_token": tokens['refresh_token']}
)
new_tokens = refresh_response.json()

Error Handling

All endpoints follow a consistent error response format:

{
  "detail": "Error message here",
  "code": "ERROR_CODE",
  "field": "field_name"  // Optional, for validation errors
}

Common error codes: - INVALID_CREDENTIALS: Wrong email or password - TOKEN_EXPIRED: Access token has expired - INVALID_TOKEN: Token is malformed or invalid - USER_NOT_FOUND: User doesn't exist - VALIDATION_ERROR: Request validation failed