Authentication and authorization

Configure Redis Agent Memory self-managed Control Plane authentication, Data Plane auth modes, worker callbacks, and gateway integration.

Self-managed Redis Agent Memory uses separate authentication models for the Control Plane and Data Plane.

The Control Plane uses an admin token for management endpoints. The Data Plane checks each agent key with the Identity Service, using the Data Plane service credential, and enforces store-level grants.

Credentials

Each generated Secret keeps its value across upgrades (helm.sh/resource-policy: keep). To bring your own, set existingSecret on the matching value.

Control Plane admin token

Control Plane management endpoints require:

Authorization: Bearer <admin-token>

Production deployments should read the token from a mounted Secret file:

profile: prod

auth:
  type: admin-token
  admin_token:
    token_file: /etc/controlplane-onprem/admin/token

The Control Plane reads the token file on each request, so rotating the Secret does not require a Control Plane redeploy.

Data Plane auth modes

The Data Plane defaults to agent-key authentication whenever no auth method is set.

Agent-key authentication

The deploy walkthrough uses agent-key authentication from the start. In the chart-rendered configuration, the chart writes the agent-key introspection settings for you, so you add nothing more.

A bring-your-own (BYO) Data Plane configuration needs the auth.agent_keys.introspection block, including a BYO configuration without auth. See Bring-your-own (BYO) configuration. The MEM_AUTH_METHOD environment variable overrides the method.

Clients send agent keys as Bearer credentials:

Authorization: Bearer <agent-key>

Treat agent keys as opaque credentials. Do not parse their contents.

Auth-disabled Data Plane

Use auth-disabled mode for development and testing only:

auth:
  method: none

Store authorization and grants

For agent-key requests, Redis Agent Memory checks both identity and resource authorization:

1. The Data Plane asks the Identity Service whether the key is valid, and caches the answer per pod.
2. The key has a grant for the requested store resource.
3. The grant includes the permission required by the operation.

Because of the cache, a revoked key stops working within up to 5 minutes (180 seconds soft, 300 seconds hard). If the Identity Service can't be reached, keys that aren't cached get 503.

A grant names the tenant, product, store, and actions:

{
  "tenant": "<your-tenant-id>",
  "product": "memory",
  "resourceType": "mem-store",
  "resourceId": "<store-id>",
  "actions": ["read", "write"]
}

Use the same tenant on every grant of a key. Any string is accepted. Use 1 if you manage stores with the Control Plane admin token.

Grant actions:

Operation mapping:

Worker callbacks

Redis Agent Memory workers consume background jobs and call the Data Plane to read session events and write extracted long-term memories.

The deploy values already enable worker callbacks. Each platform also needs the setup in Prepare worker identity for your platform.

For deployments where Redis Agent Memory Data Plane auth is enabled, workers should authenticate with Kubernetes projected service-account tokens. The Helm workerAuth.enabled preset creates or uses a worker ServiceAccount and mounts a projected token into the worker pod. The Data Plane must also be configured to validate and authorize that token through auth.worker_identity.

Minimal worker-auth values:

workerAuth:
  enabled: true

# Optional customization when the default worker ServiceAccount is not suitable.
worker:
  serviceAccount:
    name: ""        # set to use an existing ServiceAccount
    create: false   # set true to create a dedicated ServiceAccount without the preset
    annotations: {}
    token:
      audience: redis-agent-memory
      expirationSeconds: 3600
      mountPath: /var/run/secrets/redis-agent-memory-worker
      fileName: token

Matching Data Plane config:

dataplane_client:
  base_url: http://redis-agent-memory:9000
  auth:
    disabled: false
    type: service_account_token
    token_file: /var/run/secrets/redis-agent-memory-worker/token

auth:
  method: agent_key
  worker_identity:
    enabled: true
    issuer: <service-account-issuer>
    jwks_uri: "https://kubernetes.default.svc/openid/v1/jwks"
    audience:
      - redis-agent-memory
    subjects:
      - subject: "system:serviceaccount:<namespace>:redis-agent-memory-worker"
        user_id: "redis-agent-memory-worker"
        roles:
          - operator
        resources:
          "mem-store:*":
            permissions:
              - write

Worker identity access is controlled by auth.worker_identity.subjects. Configure worker identity to:

• Trust one or more exact Kubernetes service-account subjects.
• Validate worker tokens by issuer, JWKS URI, audience, and signing algorithm.
• Map each trusted subject to a Redis Agent Memory Principal with roles, scopes, and resource grants.
• Grant store access with resource keys such as mem-store:<store-id>.
• Use mem-store:* for a shared worker identity, or use narrower store grants and separate worker ServiceAccounts for stronger isolation.
• Grant read, write, or full; write implies read, and full implies write.

The Helm ServiceAccount/token settings only provide the Kubernetes credential. Redis Agent Memory authorization still comes from the server-side auth.worker_identity subject grants. With agent-key authentication, you must configure worker identity.

Gateway and identity provider integration

Use a gateway when it owns external authentication and coarse policy. For example, a gateway can authenticate callers through an identity provider before it forwards requests to Redis Agent Memory.

If the gateway also owns the standard Authorization header, forward the Agent Memory key in X-Api-Key:

Authorization: Bearer <gateway-token>
X-Api-Key: <ram-agent-key>

Redis Agent Memory uses X-Api-Key as the Redis Agent Memory credential when present. The gateway token is still available to the gateway, but Redis Agent Memory authorizes the request from the server-side grants attached to the Redis Agent Memory key.

Gateway rules:

• The gateway owns external authentication and perimeter policy.
• Redis Agent Memory owns store-level authorization.
• Redis Agent Memory keys are stored and forwarded by trusted infrastructure or trusted applications.
• Callers must not be able to bypass the gateway and reach the Data Plane directly unless they also present a valid Redis Agent Memory credential.