{
  "schema_version": 2,
  "id": "operate/iris/agent-memory/self-managed/authentication",
  "title": "Authentication and authorization",
  "url": "https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/authentication/",
  "summary": "Configure Redis Agent Memory self-managed Control Plane authentication, Data Plane auth modes, worker callbacks, and gateway integration.",
  "aliases": [
    "/develop/ai/context-engine/agent-memory/self-managed/authentication/"
  ],
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-10-21T16:40:24+03:00",
  "page_type": "content",
  "content_hash": "b326d867d862495bf1bdbcc1955b3ba5e1a05b5ca74cf4393f3cfa31998b1cbe",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Self-managed Redis 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 checks each agent\nkey with the Identity Service, using the Data Plane service credential, and enforces store-level\ngrants."
    },
    {
      "id": "credentials",
      "title": "Credentials",
      "role": "content",
      "text": "| Credential | Who presents it to whom | Secret / key | Auto-generated? | What it unlocks |\n| --- | --- | --- | --- | --- |\n| Control Plane admin token | Operator → Control Plane (`:9100`) | `redis-agent-memory-controlplane-admin-token` / `token` | Yes (`controlplane.adminToken.autoGenerate`) | Store management: `/v1/stores`, `/v1/detectors` |\n| Control Plane internal token | Identity Service → Control Plane | `memory-internal-token` / `token` in the walkthrough | You provision it for both releases | Checking that the store in a grant exists. Set `controlplane.internalToken.existingSecret` on Memory and `productValidation.products.memory.credential.existingSecret` on Identity Service. |\n| Identity Service control token | Operator → Identity Service (`:9200`) | `ids-control-token` / `token` in the walkthrough | Supplied through `control.existingSecret` on Identity Service; that chart can also generate one | Creating, listing, updating, rotating and revoking agent keys |\n| Data Plane service credential | Data Plane → Identity Service | `memory-dp-credential` / `token` in the walkthrough | You provision it for both releases | Checking agent keys for `memory`. Set `identityService.credential.existingSecret` on Memory and register it in `runtime.serviceCredentials[]` on Identity Service. |\n| Agent key | Application → Data Plane (`:9000`) | None; returned once when minted or rotated | No | The Data Plane operations its grants allow |\n\nGenerated token Secrets are retained across upgrades and uninstalls (`helm.sh/resource-policy: keep`).\nUse existing Secrets for shared credentials and for reproducible deployment automation.\nSecret names and keys must agree between releases. See\n[Secret rotation](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/operations#secret-rotation)."
    },
    {
      "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": "The Data Plane defaults to agent-key authentication whenever no auth method is set."
    },
    {
      "id": "agent-key-authentication",
      "title": "Agent-key authentication",
      "role": "content",
      "text": "The [`deploy` walkthrough](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy) uses agent-key\nauthentication from the start. In the chart-rendered configuration, the chart writes the agent-key\nintrospection settings from `dataplane.identityServiceBaseURL` and `identityService.credential`.\nThese must point to the standalone release and its registered `memory-dp` credential.\n\nA bring-your-own (BYO) Data Plane configuration needs the `auth.agent_keys.introspection` block,\nincluding a BYO configuration without `auth`. See\n[Bring-your-own (BYO) configuration](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/configuration#bring-your-own-byo-configuration).\nThe `MEM_AUTH_METHOD` environment variable overrides the method.\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": "auth-disabled-data-plane",
      "title": "Auth-disabled Data Plane",
      "role": "security",
      "text": "Use auth-disabled mode for development and testing only:\n\n[code example]\n\nThese are application configuration fields; put them under `memory` in Helm values.\nThe Data Plane refuses `auth.method: none` unless `profile` is exactly `dev`.\nChart-rendered configuration fails to render otherwise. With a supplied configuration Secret,\nthe same rule is enforced at process startup.\n\n> [!WARNING]\n> Do not expose an auth-disabled Data Plane to untrusted callers. In auth-disabled\n> mode, Redis Agent Memory does not authenticate or authorize Data Plane requests; any\n> caller that can reach the API can read or write memory for configured stores."
    },
    {
      "id": "store-authorization-and-grants",
      "title": "Store authorization and grants",
      "role": "content",
      "text": "For agent-key requests, Redis Agent Memory checks both identity and resource\nauthorization:\n\n1. The Data Plane asks the Identity Service whether the key is valid, and caches the answer per pod.\n2. The key has a grant for the requested store resource.\n3. The grant includes the permission required by the operation.\n\nBecause of the cache, a revoked key stops working within up to 5 minutes (180 seconds soft, 300\nseconds hard). If the Identity Service can't be reached, keys that aren't cached get `503`.\n\nA grant names the tenant, product, store, and actions:\n\n[code example]\n\nUse the installation's tenant on every grant, for example `default`. Set Memory's `tenantId`\nand Identity Service's `runtime.apiKeyTenant.singleTenantID` to that same value. With a rendered\nControl Plane configuration, `tenantId` sets `auth.admin_tenant_id`, so admin-token stores belong\nto that tenant too. With a supplied Control Plane configuration Secret, set `auth.admin_tenant_id`\nyourself. Neither release checks the other release's tenant setting.\n\nGrant actions:\n\n| Action | Meaning |\n| --- | --- |\n| `read` | Read and search memory data. |\n| `write` | Mutate memory data. `write` implies `read`. |\n| `full` | `full` implies `write`. |\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": "Redis Agent Memory workers consume background jobs and call the Data Plane to read\nsession events and write extracted long-term memories.\n\nThe [`deploy` values](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#3-create-ram-valuesyaml)\nalready enable worker callbacks. Each platform also needs the setup in\n[Prepare worker identity for your platform](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#prepare-worker-identity-for-your-platform).\n\nFor deployments where Redis 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 a Redis Agent Memory `Principal` with roles, scopes,\n  and resource grants.\n- Grant store access with resource keys such as `mem-store:<store-id>`.\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.\nRedis Agent Memory authorization still comes from the server-side\n`auth.worker_identity` subject grants. With agent-key authentication, you must configure worker\nidentity."
    },
    {
      "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 Redis 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\nRedis Agent Memory uses `X-Api-Key` as the Redis Agent Memory credential when present. The\ngateway token is still available to the gateway, but Redis Agent Memory authorizes the\nrequest from the server-side grants attached to the Redis Agent Memory key.\n\nGateway rules:\n\n- The gateway owns external authentication and perimeter policy.\n- Redis Agent Memory owns store-level authorization.\n- Redis 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 Redis Agent Memory credential."
    }
  ],
  "examples": [
    {
      "id": "control-plane-admin-token-ex0",
      "language": "http",
      "code": "Authorization: Bearer <admin-token>",
      "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": "agent-key-authentication-ex0",
      "language": "http",
      "code": "Authorization: Bearer <agent-key>",
      "section_id": "agent-key-authentication"
    },
    {
      "id": "auth-disabled-data-plane-ex0",
      "language": "yaml",
      "code": "profile: dev\nauth:\n  method: none",
      "section_id": "auth-disabled-data-plane"
    },
    {
      "id": "store-authorization-and-grants-ex0",
      "language": "json",
      "code": "{\n  \"tenant\": \"<your-tenant-id>\",\n  \"product\": \"memory\",\n  \"resourceType\": \"mem-store\",\n  \"resourceId\": \"<store-id>\",\n  \"actions\": [\"read\", \"write\"]\n}",
      "section_id": "store-authorization-and-grants"
    },
    {
      "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: <service-account-issuer>\n    jwks_uri: \"https://kubernetes.default.svc/openid/v1/jwks\"\n    audience:\n      - redis-agent-memory\n    subjects:\n      - subject: \"system:serviceaccount:<namespace>: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 <gateway-token>\nX-Api-Key: <ram-agent-key>",
      "section_id": "gateway-and-identity-provider-integration"
    }
  ]
}