Access control
Foundation4 authenticates every API request with an API key and authorizes the request with the permissions that the key holds. This page describes API keys, the read, write and execute permissions, the permissions that each common operation requires, classification allow-lists, which limit the content a key can search and read, and the master key. Administrators need this page to create keys for client applications, and integrators need this page to request the permissions an integration requires.
API keys
An API key consists of an identifier in universally unique identifier (UUID) format and a secret. Every request carries both, in the x-api-key and x-api-key-secret headers. Foundation4 stores each secret as an Argon2 hash and returns the secret once, in the response that creates the key. A lost secret cannot be recovered or regenerated; the key is replaced with a new key.
A key is created with POST /api-keys. The request contains the following fields.
| Field | Required | Description |
|---|---|---|
name | Yes | A name that is unique across the deployment |
description | No | Free text for administrators |
expiration | No | An expiration time in RFC 3339 format. A key without an expiration time does not expire. |
permissions | No | Permissions on object types, as an object that maps each object type to a permission level, such as {"agents": 4} |
classifications | No | The classification allow-list for the pipelines object type, described in Classification allow-lists. Without the field, the allow-list is empty and the key can use no classification: the key can neither search nor read documents through its permission on the object type. |
The response has status 201 and contains the key identifier in id and the secret in secret. POST /login with the new key's headers confirms that the key authenticates. The response has status 201 and contains the key's name, the key's permissions on object types, and admin, which is true for an admin key, described in Master key. The order of the entries in permissions can differ from one response to the next.
Permissions
A permission is a combination of three bits, written as the sum of the bits:
| Permission | Value | Grants |
|---|---|---|
| Read | 4 | Listing and retrieving objects, and reading documents |
| Write | 2 | Creating, changing and deleting objects |
| Execute | 1 | Using objects: adding documents, searching, running agents and querying LLMs |
A key with read and execute permission on a pipeline holds the value 5, and a key with all three permissions holds 7.
A permission applies at one of two scopes:
- Object type. The permission applies to every object of the type, including objects created later. Creating an object requires write permission at this scope.
- Individual object. The permission applies to one object, identified by the object's ID.
The permission of a key on an object combines the key's permission on the object type with the key's permission on the object. The object types are agents, api-keys, embedding-models, embedding-providers, llms, pipelines, taxonomies, text-splitter-providers and text-splitters. Permissions on a pipeline also govern the documents and fragments in the pipeline. No operation checks the object types contexts, context-messages, documents, fragments and permissions, and a grant on any of them returns HTTP 400 with details.error set to Permissions cannot be granted on object type <type>.
A list request returns only the objects that the key can read. A request that lacks a required permission returns HTTP 403 or HTTP 404.
Permissions by operation
The following table lists the permissions that common operations require.
| Operation | Required permissions |
|---|---|
| List or retrieve objects | Read on the object |
| List the fragments of a document, or retrieve fragments by identifier | Read and execute on the pipeline, and the fragments' classification in the allow-list |
| Create an object | Write on the object type |
| Create an embedding model or a text splitter | Write on the object type and on its provider type, embedding-providers or text-splitter-providers |
| Change or delete an object | Write on the object |
| Read a document or the versions of a document | Read on the pipeline, and the document's classification in the allow-list |
| Add a document or a new version | Execute on the pipeline, execute on the text splitter that processes the document, and the document's classification in the allow-list |
| Expire a document | Write and execute on the pipeline, and the document's classification in the allow-list |
| Delete a document | Read, write and execute on the pipeline, and the document's classification in the allow-list |
| Search a pipeline | Read and execute on the pipeline, and every classification that the request names in the allow-list |
| Execute an agent | Execute on the agent, the pipeline and the LLM |
| Query an LLM or use the OpenAI-compatible endpoint | Execute on the LLM |
| Test an embedding model | Read and execute on the embedding model |
| Change the classifications of a pipeline | Write on the pipeline, and * in the allow-list |
A key for a client application that only searches one pipeline therefore holds 5 on that pipeline. A key for a service that keeps a pipeline current holds 7 on the pipeline, so that the service can add, expire and delete documents, and 1 on the pipeline's text splitter. A key with read permission alone on a pipeline cannot search the pipeline: the search returns HTTP 404 Pipeline not found.
Classification allow-lists
A permission on a pipeline can carry a classification allow-list: the classifications of the pipeline that the key may use. The value * permits every classification of the pipeline, including classifications added later, and an empty allow-list permits no classification. The allow-list applies to the following operations:
- Search. Every search type, including the searches of agents and the search tool of the MCP server, requires each classification that the request names in the allow-list. A search that names a classification outside the allow-list returns HTTP 403, or the JSON-RPC error -32602 over MCP, and no fragment. A key with an empty allow-list cannot search the pipeline.
- Reads. Document lists and fragments requested by identifier include only content whose classification is in the allow-list. Reading a document, or the fragments of a document, outside the allow-list returns HTTP 403, and the version list of such a document is empty.
- Documents. Adding, expiring and deleting a document requires the document's classification itself in the allow-list. Adding a document with a classification outside the allow-list returns HTTP 403. Expiring or deleting every document of a pipeline requires every classification of the pipeline.
- Inheritance. For search and reads, the allow-list also covers every classification that a listed classification inherits, as described in Classifications. A key whose allow-list holds
confidentialtherefore searches and readsinternalandpubliccontent as well, but adds documents only withconfidential. - Classification management.
GET /pipelines/{id}/classificationsreturns the classifications of the allow-list and the inheritance relationships that the key can reach, as described in Classifications. Adding and removing classifications requires*.
The foundation4ai admin keys-without-classifications command lists the active keys that can read or search pipelines but whose allow-list is empty, as described in Command-line interface.
The allow-list limits what the key can reach. A search request still names the classifications of the end user, which the client application determines, as described in Classifications.
Document paths restrict no access. A key that can read a pipeline lists every path that holds a document of a classification in the key's allow-list, and a key that can search a pipeline searches under any path, as described in Document paths.
An allow-list can apply at both scopes. On the pipelines object type, the allow-list applies to every pipeline: ["*"] permits every classification of every pipeline, and a list of names permits those classifications in every pipeline that defines them. On an individual pipeline, the allow-list applies to that pipeline. When a key holds both, the key may use the classifications of both lists, each for the operations that the permission of its scope covers.
Scoped keys
A key for a client application is created in two steps: POST /api-keys creates the key, and POST /api-keys/{id}/permissions grants permissions on individual objects with the allow-list. The shell variables in the examples are described in Authenticate. The following request creates a key for a support portal:
curl -X POST "$FOUNDATION4_URL/api-keys" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"name": "support-portal-search",
"description": "Search key for the support portal",
"expiration": "2027-09-30T00:00:00Z"
}'
The response has status 201 and contains the new key. The secret field holds a generated 48-character string, shown here as a placeholder:
{
"id": "14b7d6bc-8cf7-4766-86ac-2cc66530baee",
"created_at": "2026-09-29T12:05:12.734519Z",
"updated_at": "2026-09-29T12:05:12.734519Z",
"name": "support-portal-search",
"description": "Search key for the support portal",
"secret": "change-me",
"active": true,
"expiration": "2027-09-30T00:00:00Z"
}
The following request grants read and execute permission on one pipeline, with an allow-list of two classifications. $NEW_KEY_ID holds the id of the new key.
curl -X POST "$FOUNDATION4_URL/api-keys/$NEW_KEY_ID/permissions" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"permissions": [
{"object_type": "pipelines", "object_id": "'"$PIPELINE_ID"'", "permission": 5}
],
"classifications": ["public", "internal"]
}'
The response has status 200 and an empty body. GET /api-keys/{id}/permissions returns every permission entry of the key, each with object_type, object_id, permission and, for pipelines, classifications. On other object types, classifications is null.
The permissions request follows these rules:
- Entries. Each entry names an object type, an object ID and a permission value. The object ID
00000000-0000-0000-0000-000000000000denotes the object type scope. An object type that does not exist returns HTTP 422, with a message that starts withFailed to deserialize the JSON body into the target type:. - Updates. An entry replaces the permission of the same object type and object ID. Entries not named in the request are unchanged. A permission value of 0 removes the entry.
- Allow-list. The
classificationslist applies to every pipeline entry in the request, and replaces the allow-list of those entries. A request without the list keeps the allow-list of existing entries, and creates new pipeline entries without an allow-list, so that the key can use no classification of those pipelines. Pipelines that need different lists are granted in separate requests. - Existing objects. An entry for an individual object requires that the object exists. An entry for a missing object returns HTTP 400 with
details.errorset toCannot grant permissions on <type> <id>: the object does not exist. - Atomicity. Foundation4 applies all entries of a request in one transaction. If any entry is refused, no entry changes.
Granting limits
A key can grant only what the key holds. Each granted permission must be contained in the granting key's permission on the object type, or on the object when an existing key's permissions are changed. Removing an entry with the value 0 likewise requires that the granting key holds the permission of the entry. When the granting key's allow-list on pipelines is not *, each granted classification must be in the granting key's allow-list, and removing a pipeline entry requires every classification of the entry's allow-list in the granting key's allow-list. A request beyond these limits returns HTTP 403, and details.error names the permission or the classifications, such as Your key cannot grant read and write access on pipelines, which it does not hold itself. Creating keys requires write permission on the api-keys object type, and changing a key's permissions requires write permission on that key.
The key that creates a pipeline receives all three permissions on the new pipeline, with the allow-list *. The key that creates an agent, an LLM, a taxonomy, an embedding model or a text splitter receives all three permissions on the new object. Creating an API key grants no permission on the new key to the creating key.
Key lifecycle
PATCH /api-keys/{id} changes the name, description, active and expiration fields of a key. The secret cannot be changed. Deactivating a key with "active": false, deleting a key with DELETE /api-keys/{id} and changing a key's permissions take effect on the next request. A key stops authenticating at its expiration time, and requests from that time return HTTP 401. A key cannot delete itself. The last_used_at field of a key shows the last time the key authenticated a request, recorded at most once an hour, or null when no use has been recorded.
Deleting an object, such as a pipeline or an agent, removes every key's permission entries on that object.
A key is replaced by creating a new key with the same permissions, moving the client application to the new key and deleting the old key once the old key's last_used_at no longer advances.
Master key
The master key is the administration key of a deployment. The master key holds all three permissions on the nine object types, with the allow-list *, and is used to create the scoped keys that client applications use. A key that holds these permissions is an admin key: POST /login returns "admin": true, and only an admin key reads installation-wide information, such as the license with GET /license.
The identifier and secret of the master key are set in the configuration keys app.master.key and app.master.secret, or in the environment variables FOUNDATION4AI__APP__MASTER__KEY and FOUNDATION4AI__APP__MASTER__SECRET. The identifier must be a UUID. The installation creates the master key with the foundation4ai admin create-admin-api-key command, and runs the command again at every upgrade. The workers authenticate with the master key at startup, so the master key must remain active and unexpired for documents to be processed. When the master key is expired, inactive or missing, the API server starts, logs an error, and refuses requests made with the master key. When the configured master key secret does not match the stored master key, the API server stops at startup.
The master key is rotated with the same command:
- Secret. After
app.master.secretchanges, the command replaces the stored secret, and the previous secret stops authenticating at once. - Identifier. After
app.master.keychanges, the command creates a new master key. The previous master key is renamed, keeps its admin permissions, and is deleted by an administrator once no client uses it.
The master key cannot be deleted, deactivated, given an expiration or given or stripped of permissions through the API; another key cannot change the master key at all. These requests return HTTP 403. The foundation4ai admin update-admin-api-key command changes the active flag and the expiration of the master key from the command line. The master key does not belong in client application configuration. Secrets and keys describes how the master key is stored.