API keys and permissions
How Document Intelligence API keys are created, what each key may do, and how to store and revoke them.
Sending the key
Every request carries your key in the x-api-key header (header names are case-insensitive):
curl -sS "https://futuresmart.ai/document-intelligence/api/v1" \
-H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"GET /v1 lists the collections the key can see — a quick way to check a key works.
Creating a key
Keys are created in the app, on a collection's Share → API panel, with Generate API key.
- The full key (
sk-…) is shown once, when it is created. Only a short prefix is stored, so a lost key cannot be recovered — revoke it and create another. - A key made on a collection's Share screen works on that collection only.
- The panel lists the collection's keys by prefix, each with a Revoke action. Revoked keys stop working on the next request.
What a key can and cannot do
| A key can | A key cannot |
|---|---|
| List and read its collection, its configuration and field definitions | Create or delete collections |
| Add documents (upload, URL, text or web page), one at a time or in batches | Change the collection's configuration or fields |
| Follow processing status and delete documents | Edit or delete sections |
| Search, ask questions, and read saved conversations | Delete conversations or rate answers |
| Read extracted fields per document or as a table | Manage keys, invitations, sharing or usage settings |
Calls outside that list return 403 Collection API keys cannot call this endpoint. A key used on another collection returns 403 This API key is not valid for this collection. Those actions are done in the app by a signed-in owner or editor.
A key also carries its creator's role: a key made by someone invited as a viewer can read and ask, but not add or delete documents.
Keeping keys safe
- Server side only. A key can add and delete documents. Call the API from your backend, a job or a script — never from browser JavaScript or a mobile app. For a chat box on a public website, use the collection's Share options, which need no key.
- Environment variables or a secret store. Don't commit keys. The examples in these docs read
DOCUMENT_INTELLIGENCE_API_KEYfrom the environment. - One key per integration. Create a separate key for each system that calls the API, so you can revoke one without breaking the others.
Who is billed
Everything a key does counts toward the collection owner's usage and limits, whoever created the key. See Errors and limits.
Self-hosted installations
The open-source project uses the same sk- keys. It also has an operator key (FASTAPI_SECRET_KEY) that reaches every collection and can create collections from code; its own API guide shows that flow. Give applications collection keys, not the operator key.