Authentication
API key headers, scope kinds, actions, issuance, and revocation.
Authenticate applications with an Engine API key. Choose a resource scope and permitted actions when creating a key. Keys remain valid until revoked.
Send the key
Every endpoint except /health and /ready requires a key. Send the complete secret in either Authorization: Bearer or X-API-Key. Engine keys use the prefix gek_. A key_ ID identifies a key for management and cannot authenticate a request.
GET https://engine.example.com/info
GET /info HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>Alternative authentication header
X-API-Key: <GRAPHON_ENGINE_API_KEY>Use one authentication form consistently. Keep keys in a server secret store. HTTPS is required except on loopback. Obtain the initial cluster key from the cluster operator.
Key kinds
Resource scope
Namespace: acme
Allowed collections
incident-logs · policies
Northwind is outside this boundary.
Actions
What this key can do
Scope and actions must both allow the request.
| Kind | Scope fields | Allowed boundary |
|---|---|---|
|
| All namespaces and collections, all actions, namespace administration, and key management. |
|
| One namespace. Can issue collection keys within it. |
|
| One or more named collections in one namespace. Cannot create collections or keys. |
Namespace and collection scopes require a non-empty action list. Collection scopes require at least one collection name. The API has no separate key role. Actions define the operations a key may perform.
Actions
| Action | Contract |
|---|---|
| Read allowed namespaces, collections, files, content, access rules, jobs, and the webhooks that cover them, with their delivery logs. |
| Create, update, and delete allowed data resources, change rules, reindex, cancel jobs, and manage the webhooks inside the key’s scope. Includes read. |
| Call :search and :read-spans in allowed collections. Does not include read or query. |
| Call :answer in allowed collections. Does not include read or search. |
A Search-only key can receive file IDs and spans, and read the text of spans with Read spans. It cannot GET file content, or send Read spans with raw or file in include. A collection key with write cannot create a new collection. Cluster administration and resource scope still apply.
Only a cluster key can create or manage namespaces. A namespace key can read its namespace when it has read access. A cluster key or namespace write key can change collection access_control; a collection key cannot.
Create and store a key
POST https://engine.example.com/keys
POST /keys HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json
{
"name": "acme-service",
"scope": {
"kind": "namespace",
"namespace": "acme",
"actions": [
"read",
"write",
"search",
"query"
]
}
}201 Created · illustrative secret placeholder
{
"id": "key_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
"name": "acme-service",
"prefix": "gek_",
"secret": "<NEW_ENGINE_API_KEY>",
"scope": {
"kind": "namespace",
"namespace": "acme",
"actions": [
"read",
"write",
"search",
"query"
]
},
"created_at": "2026-10-06T12:00:00Z"
}The secret appears only in the creation response. Store it immediately. Later list responses contain metadata without the secret. A namespace key can issue only collection keys in its namespace, with actions it already holds.
Keys have no expiry field. To rotate access, create a replacement, update the service, and revoke the previous key. Revoke key takes effect immediately.
Authentication and scope errors
| Status | Cause |
|---|---|
401 unauthenticated | A key is missing, invalid, or revoked. |
403 forbidden | The key can see the resource but lacks the required action. |
404 not_found | The resource does not exist or lies outside the key’s namespace or collection scope. |
A namespace key receives 404 for another namespace. A collection key receives 404 for another collection. These responses hide whether the out-of-scope resource exists.
An API key does not authenticate the principals in a retrieval request. Your application supplies those trusted names. See Access rules and Tenant keys.