Access Control
Overview
The API implements a comprehensive access control system that includes:
Authentication - JWT-based authentication with support for multiple token types
Role-Based Access Control - Different permission levels for users
Document-Level Permissions - Control who can access specific documents
Authentication
Login for Access Token
POST /tokenPurpose: Authenticates a user and provides a JWT token for subsequent API calls.
Request body:
{
"username": "user@example.com",
"password": "secure_password"
}Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer"
}Usage Example: Authentication should be performed before any other API calls.
curl -X POST "http://localhost:8000/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=user@example.com&password=secure_password"User Management
Register User
POST /users/registerPurpose: Creates a new user account (admin only).
Request body:
{
"email": "newuser@example.com",
"password": "secure_password"
}Response:
{
"email": "newuser@example.com",
"id": 42,
"is_active": true
}Usage Example:
curl -X POST "http://localhost:8000/users/register" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "newuser@example.com",
"password": "secure_password"
}'Get Current User
GET /users/mePurpose: Retrieves information about the currently authenticated user.
Response:
{
"email": "user@example.com",
"id": 42,
"is_active": true,
"roles": ["user", "admin"]
}Delete User
DELETE /users/deletePurpose: Deletes a user by email address (admin only).
Request body:
{
"email": "user@example.com"
}Response:
{
"message": "User user@example.com deleted successfully"
}Usage Example:
curl -X DELETE "http://localhost:8000/users/delete" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'Note: Users cannot delete their own admin account. Only admin users can delete other users.
Document Sharing
Share Document
POST /documents/{document_id}/sharePurpose: Shares a document with specific users.
Request body:
{
"user_emails": ["user1@example.com", "user2@example.com"]
}Response:
{
"document_id": 42,
"shared_with": ["user1@example.com", "user2@example.com"],
"status": "success"
}Usage Example: Use this endpoint to share documents with other users.
curl -X POST "http://localhost:8000/documents/42/share" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_emails": ["user1@example.com", "user2@example.com"]}'List Document Access
GET /documents/{document_id}/accessPurpose: Lists all users who have access to a document.
Response:
{
"document_id": 42,
"owner": "admin@example.com",
"shared_with": ["user1@example.com", "user2@example.com"]
}Role Management
Get User Roles
GET /users/me/rolesPurpose: Gets the roles assigned to the current user.
Response:
{
"roles": ["user", "admin"]
}Add User Role
POST /users/{user_id}/rolesPurpose: Assigns a role to a user (admin only).
Request body:
{
"role": "admin"
}Remove User Role
DELETE /users/{user_id}/roles/{role_name}Purpose: Removes a role from a user (admin only).
User Directory Management
The API supports custom ingest directories for users, allowing administrators to configure where each user's documents are stored and ingested from.
Get User Ingest Directory
GET /users/ingest-directory?email={email}Purpose: Retrieves the custom ingest directory configured for a user (admin only or self).
Query Parameters:
email(required): Email address of the user
Response:
{
"email": "user@example.com",
"ingest_directory": "/data/users/user@example.com",
"created_at": "2025-10-20T10:00:00",
"updated_at": "2025-10-20T10:00:00"
}Response (no directory configured):
{
"email": "user@example.com",
"ingest_directory": null,
"message": "No custom ingest directory configured"
}Usage Example:
curl -X GET "http://localhost:8000/users/ingest-directory?email=user@example.com" \
-H "Authorization: Bearer YOUR_TOKEN"Note: Users can view their own ingest directory, but only admins can view other users' directories.
Set User Ingest Directory
POST /users/ingest-directoryPurpose: Sets or updates the custom ingest directory for a user (admin only).
Request body:
{
"email": "user@example.com",
"directory": "/data/users/user@example.com"
}Response:
{
"email": "user@example.com",
"ingest_directory": "/data/users/user@example.com",
"created_at": "2025-10-20T10:00:00",
"updated_at": "2025-10-20T10:00:00",
"message": "Ingest directory set successfully"
}Usage Example:
curl -X POST "http://localhost:8000/users/ingest-directory" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "directory": "/data/users/user@example.com"}'Validation:
The directory path must exist on the server
Only admin users can set ingest directories
The directory path is validated before being saved
Delete User Ingest Directory
DELETE /users/ingest-directoryPurpose: Removes the custom ingest directory configuration for a user (admin only).
Request body:
{
"email": "user@example.com"
}Response:
{
"email": "user@example.com",
"ingest_directory": null,
"message": "Ingest directory deleted successfully"
}Response (no directory configured):
{
"email": "user@example.com",
"ingest_directory": null,
"message": "No custom ingest directory was configured"
}Usage Example:
curl -X DELETE "http://localhost:8000/users/ingest-directory" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'Note: Deleting the ingest directory configuration will cause the user to fall back to the default ingest directory (./).
This page is: Copyright © 2025 MariaDB. All rights reserved.
Last updated
Was this helpful?