---
title: Keys and actions
description: Combine resource scope with explicit application permissions.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Keys and actions

An API key identifies a program. A key’s scope selects resources, and its actions select operations. These two choices define what the program can do.

## Scope plus actions

*Illustration: A namespace key reaches Acme collections only. Its action list permits read and search. Query and writes require their own permissions.*

**Namespace scope with all actions**

```json
{
  "kind": "namespace",
  "namespace": "acme",
  "actions": [
    "read",
    "write",
    "search",
    "query"
  ]
}
```

The API uses actions rather than named roles. There is no `role` field on a key. A key can allow Search without allowing file reads or Query. Choose permissions for the work that each service actually performs.

## Three key kinds

| Kind | Resource boundary | Key management |
| --- | --- | --- |
| `cluster` | Every namespace and collection, with all actions. | Can create and revoke any key. |
| `namespace` | One namespace, limited by its actions. | Can create and revoke collection keys in that namespace. |
| `collection` | One or more named collections in one namespace. | Cannot create keys or collections. |

Namespace and collection keys require a non-empty `actions` list. Collection keys also require a non-empty `collections` list. A child key cannot receive actions that its creator lacks.

## Actions are independent

| Action | Permits |
| --- | --- |
| `read` | Read visible namespace, collection, file, content, access-rule, and job resources. |
| `write` | Write permitted resources, reindex, and cancel jobs. Includes read. |
| `search` | Search the permitted collections. Does not include read or query. |
| `query` | Query the permitted collections. Does not include read or search. |

Scope still applies when an action is present. A collection key with `write` cannot create another collection. A namespace key cannot manage other namespaces.

## Key lifecycle

The create response reveals the key secret once. Later list responses contain key metadata, never that secret. Store the secret in your server’s secret store. An Engine key begins with `gek_`; its management ID begins with `key_`.

Keys remain valid until revoked. To replace a key, create a replacement, update the consuming service, then revoke the previous key. Revocation applies immediately.

Read [Authentication](/engine/reference/authentication) for headers and error behavior. Follow [Isolate tenants and issue keys](/engine/guides/tenant-keys) for examples.
## Sitemap

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