{ "id": "authentication", "title": "Authentication and authorization", "url": "https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/self-managed/authentication/", "summary": "Configure Redis Agent Memory self-managed Control Plane authentication, Data Plane auth modes, worker callbacks, and gateway integration.", "tags": [ "docs", "develop", "ai" ], "last_updated": "2026-07-28T14:23:48-07:00", "page_type": "content", "content_hash": "78c6c6ca6d7ce595c9b9e28a1d6c5a4874fc6ddabd9153cc94f63bf05f8a45bd", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "Self-managed Agent Memory uses separate authentication models for the Control\nPlane and Data Plane.\n\nThe Control Plane uses an admin token for management endpoints. The Data Plane\ncan run behind infrastructure controls with Agent Memory auth disabled, or it\ncan validate Agent Memory agent keys and enforce store-level grants." }, { "id": "control-plane-admin-token", "title": "Control Plane admin token", "role": "content", "text": "Control Plane management endpoints require:\n\n[code example]\n\nProduction deployments should read the token from a mounted Secret file:\n\n[code example]\n\nThe Control Plane reads the token file on each request, so rotating the Secret\ndoes not require a Control Plane redeploy." }, { "id": "data-plane-auth-modes", "title": "Data Plane auth modes", "role": "content", "text": "Choose the Data Plane auth mode based on how callers reach the Data Plane.\n\n| Mode | Config | Use when |\n| --- | --- | --- |\n| Auth-disabled Data Plane | `auth.method: none` | The Data Plane is reachable only by trusted internal components. |\n| Agent-key authentication | `auth.method: agent_key` | Agent Memory should validate keys and enforce per-store grants. |" }, { "id": "auth-disabled-data-plane", "title": "Auth-disabled Data Plane", "role": "security", "text": "[code example]\n\nUse this only when hosting controls restrict Data Plane access to trusted\ncomponents.\n\n\nDo not expose an auth-disabled Data Plane to untrusted callers. In auth-disabled\nmode, Agent Memory does not authenticate or authorize Data Plane requests; any\ncaller that can reach the API can read or write memory for configured stores." }, { "id": "agent-key-authentication", "title": "Agent-key authentication", "role": "content", "text": "Agent-key auth requires Control Plane managed stores. The Data Plane must be\nable to load both store records and agent-key records from Metadata Redis.\n\nStarting from static store configuration, make these changes:\n\n1. Replace static `metadata.stores` with `metadata.source: live`.\n2. Configure `metadata.live.urls`, `metadata.live.namespace`, and\n `metadata.live.store_db.urls`.\n3. Set `auth.method: agent_key`.\n4. Add the `embedding` selection block.\n5. Keep `embedders_connection_details` for the embedder endpoint and\n credentials.\n6. If Agent Memory workers are enabled, configure worker identity as described in\n [Worker callbacks](#worker-callbacks) so worker-to-Data Plane calls carry an\n accepted credential.\n\nWorking Data Plane config shape for Control Plane managed stores:\n\n[code example]\n\nWhen the Data Plane uses `metadata.source: live`, Agent Memory defaults to\n`auth.method: agent_key` when no auth method is configured. Set it explicitly in\nproduction values so the intended security posture is visible in review. If\nagent-key auth is enabled without `metadata.source: live`, the Data Plane fails\nstartup with a validation error.\n\nClients send agent keys as Bearer credentials:\n\n[code example]\n\nTreat agent keys as opaque credentials. Do not parse their contents." }, { "id": "store-authorization-and-grants", "title": "Store authorization and grants", "role": "content", "text": "For agent-key requests, Agent Memory checks both identity and resource\nauthorization:\n\n1. The key exists in metadata Redis and its secret validates.\n2. The key has a grant for the requested store resource.\n3. The grant includes the permission required by the operation.\n\nGrant actions:\n\n| Action | Meaning |\n| --- | --- |\n| `read` | Read and search memory data. |\n| `write` | Mutate memory data. `write` implies `read`. |\n\nOperation mapping:\n\n| Required permission | Data Plane operations |\n| --- | --- |\n| `read` | List sessions, get session memory, get session event, get session property, search long-term memory, get long-term memory. |\n| `write` | Add/delete session events, delete session memory, set session summary, set session property, create/update/delete long-term memory. |" }, { "id": "worker-callbacks", "title": "Worker callbacks", "role": "content", "text": "Agent Memory workers consume background jobs and call the Data Plane to read\nsession events and write extracted long-term memories.\n\nFor deployments where Agent Memory Data Plane auth is enabled, workers should\nauthenticate with Kubernetes projected service-account tokens. The Helm\n`workerAuth.enabled` preset creates or uses a worker ServiceAccount and mounts a\nprojected token into the worker pod. The Data Plane must also be configured to\nvalidate and authorize that token through `auth.worker_identity`.\n\nMinimal worker-auth values:\n\n[code example]\n\nMatching Data Plane config:\n\n[code example]\n\nWorker identity access is controlled by `auth.worker_identity.subjects`.\nConfigure worker identity to:\n\n- Trust one or more exact Kubernetes service-account subjects.\n- Validate worker tokens by issuer, JWKS URI, audience, and signing algorithm.\n- Map each trusted subject to an Agent Memory `Principal` with roles, scopes,\n and resource grants.\n- Grant store access with resource keys such as `mem-store:`.\n- Use `mem-store:*` for a shared worker identity, or use narrower store grants\n and separate worker ServiceAccounts for stronger isolation.\n- Grant `read`, `write`, or `full`; `write` implies `read`, and `full` implies\n `write`.\n\nThe Helm ServiceAccount/token settings only provide the Kubernetes credential.\nAgent Memory authorization still comes from the server-side\n`auth.worker_identity` subject grants. If worker auth is not configured, keep\nthe Data Plane auth-disabled and reachable only by trusted internal components." }, { "id": "gateway-and-identity-provider-integration", "title": "Gateway and identity provider integration", "role": "content", "text": "Use a gateway when it owns external authentication and coarse policy. For\nexample, a gateway can authenticate callers through an identity provider before\nit forwards requests to Agent Memory.\n\nIf the gateway also owns the standard `Authorization` header, forward the Agent\nMemory key in `X-Api-Key`:\n\n[code example]\n\nAgent Memory uses `X-Api-Key` as the Agent Memory credential when present. The\ngateway token is still available to the gateway, but Agent Memory authorizes the\nrequest from the server-side grants attached to the Agent Memory key.\n\nGateway rules:\n\n- The gateway owns external authentication and perimeter policy.\n- Agent Memory owns store-level authorization.\n- Agent Memory keys are stored and forwarded by trusted infrastructure or\n trusted applications.\n- Callers must not be able to bypass the gateway and reach the Data Plane\n directly unless they also present a valid Agent Memory credential." } ], "examples": [ { "id": "control-plane-admin-token-ex0", "language": "http", "code": "Authorization: Bearer ", "section_id": "control-plane-admin-token" }, { "id": "control-plane-admin-token-ex1", "language": "yaml", "code": "profile: prod\n\nauth:\n type: admin-token\n admin_token:\n token_file: /etc/controlplane-onprem/admin/token", "section_id": "control-plane-admin-token" }, { "id": "auth-disabled-data-plane-ex0", "language": "yaml", "code": "auth:\n method: none", "section_id": "auth-disabled-data-plane" }, { "id": "agent-key-authentication-ex0", "language": "yaml", "code": "metadata:\n source: live\n live:\n urls:\n - redis://default:@:\n namespace: iris:memory\n store_db:\n urls:\n - redis://default:@:\n\nauth:\n method: agent_key\n\nembedding:\n provider: openai\n models:\n default_embedding_model: text-embedding-3-large\n dimensions: 3072\n\nembedders_connection_details:\n openai:\n base_url: https://api.openai.com\n credentials:\n type: static\n api_key: \"\"\n batching:\n embeddings:\n enabled: true\n max_batch_size: 10\n max_wait_time: 20ms\n num_workers: 10\n queue_size: 1000", "section_id": "agent-key-authentication" }, { "id": "agent-key-authentication-ex1", "language": "http", "code": "Authorization: Bearer ", "section_id": "agent-key-authentication" }, { "id": "worker-callbacks-ex0", "language": "yaml", "code": "workerAuth:\n enabled: true\n\n# Optional customization when the default worker ServiceAccount is not suitable.\nworker:\n serviceAccount:\n name: \"\" # set to use an existing ServiceAccount\n create: false # set true to create a dedicated ServiceAccount without the preset\n annotations: {}\n token:\n audience: redis-agent-memory\n expirationSeconds: 3600\n mountPath: /var/run/secrets/redis-agent-memory-worker\n fileName: token", "section_id": "worker-callbacks" }, { "id": "worker-callbacks-ex1", "language": "yaml", "code": "dataplane_client:\n base_url: http://redis-agent-memory:9000\n auth:\n disabled: false\n type: service_account_token\n token_file: /var/run/secrets/redis-agent-memory-worker/token\n\nauth:\n method: agent_key\n worker_identity:\n enabled: true\n issuer: \"https://kubernetes.default.svc\"\n jwks_uri: \"https://kubernetes.default.svc/openid/v1/jwks\"\n audience:\n - redis-agent-memory\n subjects:\n - subject: \"system:serviceaccount::redis-agent-memory-worker\"\n user_id: \"redis-agent-memory-worker\"\n roles:\n - operator\n resources:\n \"mem-store:*\":\n permissions:\n - write", "section_id": "worker-callbacks" }, { "id": "gateway-and-identity-provider-integration-ex0", "language": "http", "code": "Authorization: Bearer \nX-Api-Key: ", "section_id": "gateway-and-identity-provider-integration" } ] }