---
title: Authentication
description: API key headers, scope kinds, actions, issuance, and revocation.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Authentication

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**

```http
GET /info HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
```

**Alternative authentication header**

```http
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

*Illustration: A key combines its resource boundary and allowed actions. Namespace and collection keys restrict the resources visible to a program.*

| Kind | Scope fields | Allowed boundary |
| --- | --- | --- |
| `cluster` | `kind: "cluster"` | All namespaces and collections, all actions, namespace administration, and key management. |
| `namespace` | `namespace: string`, `actions: string[]` | One namespace. Can issue collection keys within it. |
| `collection` | `namespace: string`, `collections: string[]`, `actions: string[]` | 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` | Read allowed namespaces, collections, files, content, access rules, and jobs. |
| `write` | Create, update, and delete allowed data resources, change rules, reindex, and cancel jobs. Includes read. |
| `search` | Call :search in allowed collections. Does not include read or query. |
| `query` | Call :query in allowed collections. Does not include read or search. |

A Search-only key can receive file IDs and evidence but cannot GET file content. 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**

```http
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**

```json
{
  "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](/engine/reference/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](/engine/guides/access-rules) and [Tenant keys](/engine/guides/tenant-keys).
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.