{
  "schema_version": 2,
  "id": "operate/iris/langcache/self-managed/authentication",
  "title": "Authentication and authorization",
  "url": "https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication/",
  "summary": "Configure LangCache self-managed Control Plane authentication and Data Plane agent-key authentication through the Identity Service.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-09-10T15:35:47+03:00",
  "page_type": "content",
  "content_hash": "b825d3af30c014466bf4b4506d9281df8b841cfaa801b10285a563f3f96e79c3",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Self-managed LangCache uses three separate credentials:\n\n- an **admin token** for the Control Plane's cache-management API;\n- an **internal token** the Identity Service uses to validate that a\n  cache-grant reference is real, by calling back into the Control Plane;\n- **agent keys**, issued by the Identity Service, that applications use to\n  call the Data Plane.\n\nThe Data Plane always authenticates by introspecting agent keys against an\nIdentity Service. There is no auth-disabled or static-token mode for\nself-managed LangCache."
    },
    {
      "id": "control-plane-admin-token",
      "title": "Control Plane admin token",
      "role": "content",
      "text": "Control Plane management endpoints require:\n\n[code example]\n\nBy default, `controlplane.adminToken.autoGenerate: true` mints this token\ninto a chart-managed Secret on first install (stable across upgrades).\nRetrieve it:\n\n[code example]\n\nTo bring your own token instead:\n\n[code example]\n\n[code example]"
    },
    {
      "id": "control-plane-internal-token",
      "title": "Control Plane internal token",
      "role": "content",
      "text": "The internal token authenticates calls to the Control Plane's internal\ngrant-validation endpoint (`/internal/v1/grants/validate`). The Identity\nService calls this endpoint to confirm that a grant naming a LangCache cache\nresource is valid before it lets an agent key carry that grant.\n\nLike the admin token, it defaults to `controlplane.internalToken.autoGenerate: true`\nand is retrievable the same way:\n\n[code example]\n\nIn bundled Identity Service mode, the chart wires this token to the\nIdentity Service's `product_validation.langcache.credential` automatically.\nIn external mode, you must give this token to the Identity Service's owner\n(see [External Identity Service](#external-identity-service)).\n\nThe admin token and internal token must always be different values; the\nControl Plane rejects a configuration where admin token and internal token match."
    },
    {
      "id": "identity-service-modes",
      "title": "Identity Service modes",
      "role": "content",
      "text": "You must choose either Bundled Identity Service or External Identity Service at install time."
    },
    {
      "id": "bundled-identity-service",
      "title": "Bundled Identity Service",
      "role": "content",
      "text": "`identityService.mode: bundled` renders the Identity Service\nDeployment and Service, auto-generates its control token and the Data\nPlane's own runtime introspection credential, and wires everything together\nautomatically:\n\n[code example]\n\nRetrieve the auto-generated Identity Service Control admin token (used for\n`/v1/api-keys` calls, not the Data Plane's own runtime credential):\n\n[code example]\n\nThe chart also auto-generates a separate credential the Data Plane itself\nuses to call the Identity Service's introspection endpoint (scoped to\n`api-key-introspect` on product `langcache` only):\n\n[code example]"
    },
    {
      "id": "external-identity-service",
      "title": "External Identity Service",
      "role": "content",
      "text": "`identityService.mode: external` renders no Identity Service workload at\nall — use this when your suite already runs one, for example alongside\nself-managed Redis Agent Memory:\n\n[code example]\n\nThe `langcache-dp-ids-credential` is minted out of band by the suite-level\nIdentity Service owner, scoped to `api-key-introspect` on product\n`langcache`. You must also ask that owner to configure the external\nIdentity Service's own `product_validation.langcache` against this\nrelease's Control Plane internal Service\n(`langcache-controlplane:9100`) and this release's `controlplane.internalToken`\nSecret — this chart has no way to reach into an Identity Service it doesn't\nown."
    },
    {
      "id": "minting-and-managing-agent-keys",
      "title": "Minting and managing agent keys",
      "role": "content",
      "text": "Mint, list, update, revoke, and rotate agent keys directly against the\nIdentity Service (not the LangCache Control Plane):\n\n[code example]\n\nThe response contains the new credential. Store it immediately; credentials\nare returned only when a key is minted or rotated.\n\nGrant actions:\n\n| Action | Meaning |\n| --- | --- |\n| `read` | Read and search cache entries. |\n| `write` | Mutate cache entries. `write` implies `read`. |\n| `full` | Full cache access through the grant. `full` implies `write`. This is a resource permission, not a substitute for the Control Plane admin token; it doesn't grant access to Control Plane administration APIs. |\n\nClients send agent keys as Bearer credentials to the Data Plane:\n\n[code example]\n\nTreat agent keys as opaque credentials. Do not parse their contents."
    },
    {
      "id": "cache-authorization",
      "title": "Cache authorization",
      "role": "content",
      "text": "For agent-key requests, the Data Plane checks both identity and resource\nauthorization through the Identity Service:\n\n1. The key exists and its secret validates.\n2. The key has a grant for the requested cache resource, keyed as\n   `lc-cache:<cache-id>`.\n3. The grant includes the permission required by the operation."
    },
    {
      "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\nbefore it forwards requests to LangCache.\n\nGateway rules:\n\n- The gateway owns external authentication and perimeter policy.\n- LangCache owns cache-level authorization through the Identity Service.\n- LangCache agent 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 LangCache agent key."
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "With an admin token, internal token, and agent key in hand, see\n[API examples](https://redis.io/docs/latest/operate/iris/langcache/self-managed/api-examples)\nto create a cache and start calling the Data Plane, or\n[Operations](https://redis.io/docs/latest/operate/iris/langcache/self-managed/operations)\nto rotate these credentials going forward."
    }
  ],
  "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": "bash",
      "code": "kubectl -n <namespace-name> get secret langcache-controlplane-admin-token \\\n  -o jsonpath=\"{.data.token}\" | base64 -d",
      "section_id": "control-plane-admin-token"
    },
    {
      "id": "control-plane-admin-token-ex2",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic langcache-controlplane-admin-token \\\n  --from-literal=token='<admin-token>'",
      "section_id": "control-plane-admin-token"
    },
    {
      "id": "control-plane-admin-token-ex3",
      "language": "yaml",
      "code": "controlplane:\n  adminToken:\n    existingSecret: langcache-controlplane-admin-token\n    autoGenerate: false",
      "section_id": "control-plane-admin-token"
    },
    {
      "id": "control-plane-internal-token-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret langcache-controlplane-internal-token \\\n  -o jsonpath=\"{.data.token}\" | base64 -d",
      "section_id": "control-plane-internal-token"
    },
    {
      "id": "bundled-identity-service-ex0",
      "language": "yaml",
      "code": "identityService:\n  mode: bundled\n  bundled:\n    image:\n      repository: redislabs/iris-identity-service\n      tag: \"<langcache-version>\"\n    metadata:\n      existingSecret: ids-metadata",
      "section_id": "bundled-identity-service"
    },
    {
      "id": "bundled-identity-service-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret langcache-identity-service-control-token \\\n  -o jsonpath=\"{.data.token}\" | base64 -d",
      "section_id": "bundled-identity-service"
    },
    {
      "id": "bundled-identity-service-ex2",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret langcache-identity-service-dp-credential \\\n  -o jsonpath=\"{.data.token}\" | base64 -d",
      "section_id": "bundled-identity-service"
    },
    {
      "id": "external-identity-service-ex0",
      "language": "yaml",
      "code": "identityService:\n  mode: external\n  external:\n    baseURL: https://suite-identity-service.example.com\n    credential:\n      existingSecret: langcache-dp-ids-credential\n      secretKey: token",
      "section_id": "external-identity-service"
    },
    {
      "id": "minting-and-managing-agent-keys-ex0",
      "language": "bash",
      "code": "IDS_URL=\"http://localhost:9200\"\nIDS_CONTROL_TOKEN=\"<identity-service-control-token>\"\n\ncurl -sS -X POST \"$IDS_URL/v1/api-keys\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-agent-key\",\n    \"grants\": [\n      {\n        \"product\": \"langcache\",\n        \"resourceType\": \"lc-cache\",\n        \"resourceId\": \"<cache-id>\",\n        \"actions\": [\"read\", \"write\"]\n      }\n    ]\n  }'",
      "section_id": "minting-and-managing-agent-keys"
    },
    {
      "id": "minting-and-managing-agent-keys-ex1",
      "language": "http",
      "code": "Authorization: Bearer <agent-key>",
      "section_id": "minting-and-managing-agent-keys"
    }
  ]
}