Keys and actions

AI Draft

Combine resource scope with explicit application permissions.

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

Resource scope

Namespace: acme

Allowed collections

incident-logs · policies

Northwind is outside this boundary.

Actions

What this key can do

✓ read✓ search— write— query

Scope and actions must both allow the request.

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

{
  "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 for headers and error behavior. Follow Isolate tenants and issue keys for examples.

Was this page helpful?