Skip to content

API Documentation

🔐 Authentication Overview

All API endpoints require authentication EXCEPT: - POST /api/v1/auth/register - Public (for user registration) - POST /api/v1/auth/login - Public (for user login)

All other endpoints require the Authorization header: 

Authorization: Bearer <access_token>

Protected Endpoint Groups: - ✅ /api/v1/users/* - All user management endpoints - ✅ /api/v1/files/* - All file operations - ✅ /api/v1/broadcasting/* - All broadcasting endpoints (including WebSocket)

Authentication

Register a new user

POST /api/v1/auth/register

Request body: 

{
    "email": "user@example.com",
    "password": "Test@12345",
    "full_name": "string",
    "is_superuser": false
}

Note: Password requirements: - Minimum 8 characters - Maximum 512 characters (bcrypt limitation handled automatically) - At least one uppercase letter - At least one lowercase letter - At least one digit

Response: 

{
    "id": 1,
    "email": "user@example.com",
    "full_name": "string",
    "is_active": true,
    "is_superuser": false,
    "created_at": "2025-12-18T07:40:47.076834",
    "updated_at": "2025-12-18T07:40:47.076838"
}

Note: After registration, use the /api/v1/auth/login endpoint to get an authorization token.

Login

POST /api/v1/auth/login

Request body (form data): 

username: user@example.com
password: Test@12345

Response: 

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "user": {
        "id": 1,
        "email": "user@example.com",
        "full_name": "string",
        "is_active": true,
        "is_superuser": false,
        "created_at": "2025-12-18T07:40:47.076834",
        "updated_at": "2025-12-18T07:40:47.076838"
    }
}

Note: The login response includes both the authorization token and complete user information for immediate use in your application.

Authentication Required

⚠️ IMPORTANT: All API endpoints except /api/v1/auth/login and /api/v1/auth/register require authentication.

To authenticate, include the Authorization header in your requests:

Authorization: Bearer <access_token>

Where <access_token> is the token received from the login endpoint.

Example: 

curl -X GET http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Unauthenticated requests will return: 

{
  "detail": "Not authenticated"
}

Protected Endpoints: - ✅ All /api/v1/users/* endpoints - ✅ All /api/v1/files/* endpoints
- ✅ All /api/v1/broadcasting/* endpoints (including WebSocket)

Public Endpoints: - ❌ /api/v1/auth/login - Public (no authentication) - ❌ /api/v1/auth/register - Public (no authentication)

Users

Get current user

GET /api/v1/users/me

Headers: 

Authorization: Bearer <access_token>

Response: 

{
    "email": "user@example.com",
    "full_name": "string",
    "is_active": true,
    "is_superuser": false,
    "id": 1,
    "created_at": "2024-03-19T00:00:00",
    "updated_at": "2024-03-19T00:00:00"
}

Update current user

PUT /api/v1/users/me

Headers: 

Authorization: Bearer <access_token>

Request body: 

{
    "email": "newemail@example.com",
    "full_name": "New Name",
    "password": "newpassword"
}

Response: 

{
    "email": "newemail@example.com",
    "full_name": "New Name",
    "is_active": true,
    "is_superuser": false,
    "id": 1,
    "created_at": "2024-03-19T00:00:00",
    "updated_at": "2024-03-19T00:00:00"
}

Get all users

GET /api/v1/users?skip=0&limit=100

Headers: 

Authorization: Bearer <access_token>

Response: 

[
    {
        "email": "user1@example.com",
        "full_name": "User One",
        "is_active": true,
        "is_superuser": false,
        "id": 1,
        "created_at": "2024-03-19T00:00:00",
        "updated_at": "2024-03-19T00:00:00"
    },
    {
        "email": "user2@example.com",
        "full_name": "User Two",
        "is_active": true,
        "is_superuser": false,
        "id": 2,
        "created_at": "2024-03-19T00:00:00",
        "updated_at": "2024-03-19T00:00:00"
    }
]

Error Responses

400 Bad Request

{
    "detail": "The user with this email already exists in the system."
}

401 Unauthorized

Missing or Invalid Token: 

{
    "detail": "Not authenticated"
}

Invalid Credentials (Login): 

{
    "detail": "Incorrect email or password",
    "headers": {
        "WWW-Authenticate": "Bearer"
    }
}

Invalid Token: 

{
    "detail": "Could not validate credentials"
}

403 Forbidden

{
    "detail": "Could not validate credentials"
}

404 Not Found

{
    "detail": "User not found"
}