API Authentication & User Management

This document outlines the authentication mechanisms and user management capabilities of the Palletizing API.

User Management (`/admin`)

The API includes a built-in user management dashboard accessible via the /admin endpoint. This is a web-based HTML interface intended to be used directly from a browser.

Access: To access the admin panel, you must log in using an account that has is_administrator privileges.
Functionality: From the dashboard, administrators can:
View all existing API users.
Create new users (/admin/add).
Edit existing users (/admin/edit/{user_id}) to update their username, password, or permissions.
Delete users (/admin/delete/{user_id}).
Permissions: Two main permission flags can be assigned to users:
Administrator: Grants access to the /admin interface and administrative API endpoints.
Edit Data: Grants permission to endpoints that modify data.
Session Management: The admin interface uses an HTTP-only browser cookie (admin_access_token) to maintain the authenticated session state in the browser.

API Authentication

For programmatic access to secure API endpoints (like those defined in api/routers/secure_access.py), the application uses OAuth2 with Password Flow and JWT (JSON Web Tokens).

1. Obtaining an Access Token

To authenticate, clients must submit their credentials to the /token endpoint. The credentials must be passed as application/x-www-form-urlencoded form data (not as a JSON body).

Here is an example using Python's requests library:

import requests

BASE_URL = "http://127.0.0.1:8000"

login_data = {
    "username": "test_user",
    "password": "secret_password"
}

# Send a POST request to the /token endpoint with form data
response = requests.post(f"{BASE_URL}/token", data=login_data)

if response.status_code == 200:
    token_info = response.json()
    access_token = token_info.get("access_token")
    print("Successfully obtained access token!")
else:
    print(f"Failed to login: {response.status_code}")
    print(response.text)

2. Accessing Secure Endpoints

Once you have the access_token, you must include it in the Authorization header of all subsequent requests to secure endpoints. The header format must be Bearer <your_token>.

# Setup the authorization header
headers = {"Authorization": f"Bearer {access_token}"}

# Request a protected endpoint
secure_response = requests.get(f"{BASE_URL}/secure_access", headers=headers)

if secure_response.status_code == 200:
    print("Successfully accessed secure endpoint:")
    print(secure_response.json())
else:
    print(f"Access Denied: {secure_response.status_code}")

Authorization Levels

Depending on the endpoint's configuration, different access levels might be enforced: - Standard Access: Requires a valid JWT token (Depends(get_current_user)). - Data Editor Access: Requires a token from a user with the can_edit_data flag (Depends(require_data_edit)). - Administrator Access: Requires a token from a user with the is_administrator flag (Depends(require_administrator)).