Skip to main content
Version: 0.12.0

API keys for memory

Introduced 0.12.0

An API key is a native, revocable personal access token (PAT) — an id plus a high-entropy secret, bound to an identity and a bounded set of roles, expiring on a schedule. It is the practical way for a person or an agent to authenticate to the memory verbs without embedding a password or minting a fresh JWT for every call. Because a key authenticates a real identity, memory's organization/user isolation applies to key-authenticated calls exactly as it does to any other — see Memory tenancy and isolation.

tip

API keys are a security-plugin feature, not memory-specific — they authenticate to the whole cluster. This page covers only what is memory-specific: which roles to grant a key and how its backend roles source the organization. For the full mechanics — enabling the authenticator, the settings, and the create/use/list/get/revoke API — see the authoritative reference: API keys (personal access tokens).

Table of contents

Before you start​

API keys must be enabled and the authenticator turned on before a key can log in to the memory verbs. Both steps — the plugins.security.apikey.enabled feature flag (default true) and the apikey_auth_domain in the security config.yml (default off, and ordered before the challenging basic domain) — are described in Enable API keys. The rest of this page assumes both are in place.

Mint a key for memory​

Create a key with PUT /_plugins/_security/api/apikey. For memory, two body fields matter most: the security role that grants memory access, and the backend role that sources the organization.

PUT /_plugins/_security/api/apikey
{
  "name": "acme-analyst-7",
  "security_roles": ["memory_read_write"],
  "backend_roles": ["org:acme"],
  "expiration": "30d"
}

The response returns the token once as api_key (a base64 encoding of id:secret); capture it immediately, as it is never shown again:

{
  "id": "k0fjR7AlrLw1MQPHpV2USw",
  "name": "acme-analyst-7",
  "api_key": "azLThjJhLi4uLi4uOnNlY3JldA==",
  "expiration_at": 1786592950504
}

Keep the id — it is what you pass to revoke the token (DELETE /_plugins/_security/api/apikey/{id}). Send the api_key on each request with the ApiKey scheme:

POST /_plugins/_memory/recall
Authorization: ApiKey azLThjJhLi4uLi4uOnNlY3JldA==
Content-Type: application/json

{ "query": "which port are we analyzing?", "k": 5 }

For the full request/response shapes and the list/get/revoke endpoints, see the general reference.

Grant the right memory role​

warning

Give a key only the memory role it needs. A caller can only grant a key roles it already holds, and a key with no roles inherits the creator's roles (see Limit-by-owner). Grant memory access explicitly with exactly the memory role required — for example memory_read for a read-only assistant, or memory_read_write for one that also stores memories — rather than handing the key a broader role set.

Source the organization from a backend role​

note

For memory tenancy, the key's backend roles matter. If your deployment sources the organization from a backend-role prefix (see Enterprise authentication for memory), give the key the matching backend role — for example org:acme — so calls made with it resolve to the right organization. If instead you source the organization from a JWT or attribute, the key's owner identity carries it and no backend role is needed.