Authentication

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

Authentication Methods

Method	Header	Use Case
API Key	X-API-Key	Programmatic API access
Admin Key	X-API-Key (with admin key value)	Self-hosted administrative operations
Session	X-Session-Token	Browser-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

API keys are created and managed by each organization, in the web UI:

1. Agents & API page

The main way to manage API keys is through the web UI at Agents & API → API Keys (/api-and-agents?tab=api_keys).

From that tab you can:

• create a new API key, choosing its permissions and, optionally, the projects it may reach
• change a key's permissions, projects or description (the pencil button next to it); the key itself stays the same, so nothing needs updating where it is used, and the change applies from the key's next request
• revoke an existing API key
• turn a personal key into an integration key (administrators; the building button next to it), keeping its secret
• 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

When you create a key, you choose:

• Its type. A personal key acts as you: it can do only what you can do at the moment of each request, in the projects you can open, and it stops working if you are deactivated or leave the organization. An integration key belongs to the organization: it keeps exactly the permissions and projects chosen for it, whoever leaves. Only administrators are offered the choice; everyone else creates personal keys. Use an integration key for anything production depends on.
• What it is for. Shown in the key list and recorded against everything the key does. An integration key that may accept or reject a review (the Approve transactions or Reject transactions permission) must have a name: it is what reviewers see as the one who decided, in the review history, the export and on each value the key corrects, so the dialog asks for it and does not save the key without it. A personal key is not asked, because its decisions are recorded under the person who owns it.
• Its permissions. Start from one of your organization's roles, built-in or custom, then expand the permission list to add or remove single permissions (a search box finds one quickly). A key can never carry a permission you do not hold yourself, so a role you only partly hold is applied without the rest, and the dialog says how many were left out. When no role fits, an administrator can create a custom role on Team → Roles and you can start from it.
• Its projects. For a personal key, all your projects, which follows you into projects you are given later, or only the projects you list. For an integration key, every project, including ones created later, or only the projects you list. The key is refused anywhere else, whatever its permissions say.

The key is shown once, when it is created. Store it as a secret, never in code, and never paste it into a chat, including the assistant in DocAI Fabric, which cannot create keys for you.

Who can do what. Two permissions decide it. Create personal API keys and connect agents (credential.manage_own, held by the built-in Admin and Designer roles) lets a person create personal keys and see the Agents & API page. Someone who holds it without managing integration keys sees only their own keys and none of the integration options, and without permission to submit documents only the Agents (MCP) and API keys tabs. Manage integration keys and agents (credential.manage_integration, held by the built-in Admin role only) lets a person create integration keys, turn a personal key into one, and change or revoke anyone's key. A key never holds a permission its creator does not hold in the projects it reaches; a key with full access to the organization takes someone who holds every permission, which in practice means an administrator. You can always narrow or revoke your own personal key, even after losing the permission to create one. A key created before keys had permissions has full access: open it with the pencil button and choose its permissions to limit it without replacing it. Administrators are emailed when a key gains a permission or a project.

When a person leaves. Their personal keys stop working on their next request, and so does any integration that uses one. The keys list marks them Stopped with the reason, and Team → Remove lists the person's working personal keys, with when each was last used, before you confirm, so you can transfer the ones an integration needs to the organization first. A stopped key works again if the person is reactivated, or once it is transferred. Keys created before personal and integration keys existed were sorted once, on upgrade: those created by an administrator or through the Admin API became integration keys and work as before, those created by anyone else became personal keys, and those whose creator had already left were revoked.

Support keys. When your deployment's administrator needs to work in your organization, for a support request, they open a support key: an integration key with the permissions they chose and the reason they gave, which stops on its own after a few hours. It is listed with a Support badge, administrators get an email when one is opened, and you can revoke it like any other key. It is in your security audit log, opened and closed.

One key, one organization. Every API key belongs to one organization and reaches that organization only. The clients that the Admin API's /admin/clients made, which could reach several organizations or all of them, were removed on 2026-11-02; a key of such a client is refused with 401 and error_code client_not_tenant_scoped. Create an integration key on the Agents & API page of each organization it worked for instead.

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.

An administrator key issued with the admin key (da admin keys create) works in the same header for the routes its scopes open. On any other route it gets 403, with error_code admin_key_scope (the route needs another scope), admin_key_read_only (a read-only key on a write) or admin_key_root_only (only the admin key opens it). See Administrator keys.

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

Admin endpoints include:

• Tenants and their limits (/admin/tenants, /admin/tenants/{tenant_id})
• Support keys into a tenant (/admin/tenants/{tenant_id}/support-keys), which the tenant sees: see Support keys
• Administrator keys (/admin/keys)
• Configuration reload (/admin/reload-configs)
• Endpoint health (/admin/endpoints/health)

The admin key never mints a tenant's own API keys: those are the tenant's, on its Agents & API page.

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 on the Agents & API page
• Use least privilege: create keys with only the permissions needed