Skip to main content

Authentication

DocAI Fabric supports multiple authentication methods depending on the type of access.

Authentication Methods​

MethodHeaderUse Case
API KeyX-API-KeyProgrammatic API access
Admin KeyX-API-Key (with admin key value)Self-hosted administrative operations
SessionX-Session-TokenBrowser-based UI access

API Key Authentication​

API keys are the primary method for programmatic access. Include the key in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  https://app.docaifabric.com/api/v1/projects

Managing API Keys​

There are two ways to create and manage API keys:

  1. Integrations page (recommended)

The main way to manage API keys is through the web UI at Settings → Integrations (/integration).

From the Integrations page you can:

  • create a new API key
  • revoke an existing API key
  • rotate a key by creating a new one, updating your integration to use the new key, confirming requests succeed, and then revoking the old key
  1. Admin API (self-hosted only)

Self-hosted deployments can also manage API keys through the Admin API using the X-API-Key header with the admin key value:

Step 1: Create a client

curl -X POST "https://app.docaifabric.com/admin/clients" \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "my_integration",
    "name": "My Integration",
    "permissions": ["classify", "extract", "split"]
  }'

The response confirms the client was created:

{
  "client_id": "my_integration",
  "name": "My Integration",
  "permissions": ["classify", "extract", "split"],
  "has_api_key": false,
  "total_api_keys": 0,
  "active_api_keys": 0
}

Step 2: Generate an API key for the client

curl -X POST "https://app.docaifabric.com/admin/clients/my_integration/keys" \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production key"
  }'

The response includes the generated API key (save it, it will not be shown again):

{
  "api_key": "generated-api-key",
  "key_id": "key_abc123",
  "key_suffix": "a1b2",
  "client_id": "my_integration",
  "client_name": "My Integration",
  "description": "Production key"
}

To revoke an API key, delete it by key_id:

curl -X DELETE "https://app.docaifabric.com/admin/clients/{client_id}/keys/{key_id}" \
  -H "X-API-Key: your-admin-key"

For rotation, create a new key first, update your integration to use it, verify requests succeed, and then revoke the old key.

Admin Key Authentication​

Administrative endpoints use the same X-API-Key header, but with the admin key value (configured via the ADMIN_API_KEY environment variable).

This authentication method is available only for self-hosted deployments.

curl -H "X-API-Key: your-admin-key" \
  https://app.docaifabric.com/admin/clients

Admin endpoints include:

  • Client management (/admin/clients, /admin/clients/{client_id})
  • API key management (/admin/clients/{client_id}/keys)
  • Configuration reload (/admin/reload-configs)
  • Endpoint health (/admin/endpoints/health)

Session Authentication​

The web UI uses token-based session authentication:

  1. Users sign in via the /auth/login endpoint
  2. A session token is returned in the response body
  3. Subsequent requests include the token in the X-Session-Token header

Security Best Practices​

  • Never expose API keys in client-side code or version control
  • Rotate keys periodically using the Integrations page or, for self-hosted deployments, the Admin API
  • Use least privilege: create keys with only the permissions needed