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 by default. It also accepts operator tokens when OpenID Connect (OIDC) authentication is configured. The Data Plane checks each agent key with the Identity Service, using the Data Plane service credential, and enforces store-level grants.
Credentials
| Credential | Who presents it to whom | Secret / key | Auto-generated? | What it unlocks |
|---|---|---|---|---|
| Control Plane admin token | Operator → Control Plane (:9100) |
iris-memory-admin-token / token |
Yes, by the suite | Store and extractor management through the /iris/v1/agent-memory admin API |
| Control Plane internal token | Identity Service → Control Plane | iris-memory-internal-token / memory |
Yes, by the suite | Checking that the store in a grant exists |
| Identity Service control token | Operator → Identity Service (:9200) |
iris-identity-service-control-token / token |
Yes, by the suite | Creating, listing, updating, rotating and revoking agent keys |
| Data Plane service credential | Data Plane → Identity Service | iris-memory-dataplane-credential / memory-dp |
Yes, by the suite | Checking agent keys for memory |
| Agent key | Application → Data Plane (:9000) |
None; returned once when minted or rotated | No | The Data Plane operations its grants allow |
The suite keeps generated Secrets across upgrades, rollbacks, and uninstalls. To supply your own, see Credentials. To rotate them, see Secret rotation.
Control Plane admin token
With the default configuration, 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 only when the configuration sets no auth method. It also must enable no other auth provider, such as OIDC or worker identity. Set auth.method: agent_key explicitly, so that the security posture is visible in review.
Agent-key authentication
The deploy walkthrough uses agent-key
authentication from the start. In the chart-rendered configuration, the suite writes the agent-key
introspection settings for its Identity Service, iris-identity-service, and Memory's
memory-dp credential.
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:
profile: dev
ownership:
enabled: false
auth:
method: none
These are application configuration fields; put them under memory.memory in iris-values.yaml.
The Data Plane refuses auth.method: none unless profile is exactly dev.
Chart-rendered configuration fails to render otherwise. With a supplied configuration Secret,
the same rule is enforced at process startup.
Do not expose an auth-disabled Data Plane to untrusted callers. In auth-disabled mode, Redis Agent Memory does not authenticate or authorize Data Plane requests; any caller that can reach the API can read or write memory for configured stores.
Store authorization and grants
For agent-key requests, Redis Agent Memory checks both identity and resource authorization:
- The Data Plane asks the Identity Service whether the key is valid, and caches the answer per pod.
- The key has a grant for the requested store resource.
- 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 installation's tenant, global.iris.tenantId (default default), on every grant. The
suite applies it to Memory, the Identity Service, and the rendered Control Plane configuration's
auth.admin_tenant_id. With a supplied Control Plane configuration Secret, set
auth.admin_tenant_id yourself.
Grant actions:
| Action | Meaning |
|---|---|
read |
Read and search memory data. |
write |
Mutate memory data. write implies read. |
full |
full implies write. |
Operation mapping:
| Required permission | Data Plane operations |
|---|---|
read |
List sessions, get session memory, get session event, get session property, search long-term memory, get long-term memory. |
write |
Add/delete session events, delete session memory, set session summary, set session property, create/update/delete long-term memory. |
Server-side ownership enforcement
Store grants authorize access to a store. Ownership enforcement adds a check within that store: ordinary callers can access their own personal records and shared records.
This section applies to on-prem deployments. Ownership enforcement is off by default in the on-prem server, worker, and chart. Turn it on with memory.memory.ownership.enabled: true after you configure a user identity; see Enable or change ownership enforcement.
| Setting | Personal access | Shared access |
|---|---|---|
ownership.enabled: false |
Your trusted backend must authorize every read and write, including direct-ID requests. Owner fields and filters do not authenticate the user. | Your backend checks which shared namespaces the user may access. |
ownership.enabled: true |
The server compares the stored owner with the authenticated user ID. Search and list restrictions apply in addition to client filters. | Callers with the required store permission can access shared records. Shared scope does not enforce team membership. |
Keep application-specific checks in your backend in both modes. Use separate stores and grants if teams need separate server-enforced access. Worker credentials are for background services; do not give them to applications.
Match stored owners to authenticated users
Use the same stable user ID in stored records and the verified user token. Matching is exact, including case. IDs must meet the format in the API reference; an email address or an identity-provider subject containing punctuation may need a separate compatible claim. Changing a claim mapping does not rewrite stored owners.
The first session event's actorId becomes the session owner. Later events in an accessible session can use an assistant's actor ID without changing ownership. Directly created memories and personal namespace roots use the ownerId supplied by your application. Session extraction inherits the session owner. See Identify users and conversations for client and server fields.
With enforcement on:
- A new personal owner, or an owner update, must match the authenticated user ID. A mismatch returns
403 Forbidden, including when the record would enter a shared namespace. - Another user's personal record is hidden from direct-ID reads and mutations with
404 Not Found. Search and list filters cannot expand access. - A personal namespace child inherits its root's owner.
- A caller without a user ID can access shared records within its grants, but cannot claim a named personal owner. Ownerless private records are hidden.
Agent keys created by POST /v1/api-keys have no user binding by default, and a key never copies its creator's identity. To bind a key to one user, set identityService.apiKeys.userBinding.enabled: true (default false) and send userId when you mint the key. The control token and a suite_admin can set any user ID; other callers can set only their own. The Data Plane then uses that user ID for the key's requests. For an application that acts for many users, use delegation instead. Configuring an OpenID Connect (OIDC) claim alone does not bind a key.
An unbound key can pass store health checks and access allowed shared data while personal creation returns 403. A successful health check does not establish a user identity.
Delegate a user with an agent key
Delegation lets an application use its agent key for store permissions and a user's access token for personal identity. This path is supported in on-prem release 1.0.0. It does not add the user's store grants to the key.
- Configure your identity provider to issue signed access tokens with an issuer, a compatible user ID claim, and the intended audience. Obtain the user's token through your application's login process.
- Set that issuer and its JSON Web Key Set (JWKS) in
global.iris.auth.oidc. The suite applies them to the Data Plane. - Enable delegation and choose an audience distinct from direct OIDC sign-in.
- Send both credentials on each request for that user.
For chart-rendered configuration, merge this fragment into iris-values.yaml:
memory:
memory:
ownership:
enabled: true
auth:
oidc:
enabled: true
user_id_claim: sub
allow_azp_fallback: false
delegation:
enabled: true
audience:
- api://memory-delegation
The suite fills in the issuer, JWKS URL, and audience from global.iris.auth.oidc, and the static
tenant from global.iris.tenantId. See
Ownership and delegation with the suite chart. For a bring-your-own configuration file, place ownership and auth at the root, set auth.oidc.static_tenant_id to that same tenant, and set auth.oidc.audience to the direct-sign-in audience as a list. Do not also configure tenant_id_claim for a single-tenant deployment.
The server verifies the token's signature, issuer, audience, expiry, tenant, and user claim. JWKS verification does not decrypt a token or exchange it for another credential. An application-issued signed JSON Web Token (JWT) works only when the deployment trusts its issuer and verification keys.
Delegation defaults to off and requires OIDC to be enabled. Its audience must not overlap the direct OIDC audience; keep allow_azp_fallback off with a separate delegation audience. Without a separate audience, the same user token can also be presented as a direct sign-in.
Direct OIDC sign-in remains a preview in this release: it validates the token but does not resolve the subject's store grants. A valid token alone receives 403 for store operations. Use the agent key and delegated token together for personal access.
Set USER_TOKEN to the access token for the current request's user, and OWNER_ID to that token's verified user ID. Use the connection values from the quickstart. These examples list that user's session metadata:
import asyncio
import os
import httpx
from redis_agent_memory import AgentMemory
async def main():
async with httpx.AsyncClient(
headers={"X-Iris-User-Token": os.environ["USER_TOKEN"]},
) as transport:
async with AgentMemory(
server_url=os.environ["AGENT_MEMORY_URL"],
store_id=os.environ["STORE_ID"],
api_key=os.environ["API_KEY"],
async_client=transport,
) as memory:
page = await memory.list_sessions_async(
owner_id=os.environ["OWNER_ID"], limit=20,
)
print(page.model_dump_json(by_alias=True))
asyncio.run(main())
Create a separate request-scoped client or transport for each user's token. Do not change a shared client's user header while it handles concurrent requests.
A missing or invalid primary credential, an invalid or expired user token, or a missing user identity returns 401. A token from another tenant, or a delegation header used with a credential other than an agent key, returns 403. A valid delegated user still needs the key's store grant.
Enable or change ownership enforcement
For a new deployment that enables enforcement, configure the user-identity path before writing personal data. If your application does not use a trusted identity provider, leave enforcement off and apply backend authorization.
Before upgrading an existing deployment:
- Keep
memory.memory.ownership.enabled: falseexplicitly set while preparing the transition. - Compare stored personal owners with the verified user IDs your application will send. Resolve owner mismatches before enabling enforcement; the setting does not rewrite owners.
- Configure delegation, then set
memory.memory.ownership.enabled: truein chart-rendered values. For a bring-your-own file, useownership.enabled: trueat the root. - Apply the setting to both Data Plane servers and workers, then roll out those processes.
MEM_OWNERSHIP_ENABLEDoverrides the file value; check both for conflicting settings. - Replace existing Summary Views when changing this setting. A view retains the source-access policy from its creation.
- Test two users: each can access their own personal records, neither can retrieve or search for the other's records, and both can access shared records allowed by their store grants.
- Test an agent key without a user token: it must not retrieve personal records or create a session for a named owner.
For the two-user read check, use an ordinary agent key with store read access, without operator privileges. Set USER_TOKEN to the first user's valid token. Set OWN_SESSION_ID, OTHER_SESSION_ID, and SHARED_SESSION_ID to existing sessions owned by that user, owned by the other user, and placed in a shared namespace, respectively:
for session_id in "$OWN_SESSION_ID" "$OTHER_SESSION_ID" "$SHARED_SESSION_ID"; do
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
--header "Authorization: Bearer $API_KEY" \
--header "X-Iris-User-Token: $USER_TOKEN" \
"$AGENT_MEMORY_URL/iris/data/v1/agent-memory/stores/$STORE_ID/sessions/$session_id"
done
Expect 200, 404, and 200, in that order. Repeat with the second user's token and swap OWN_SESSION_ID with OTHER_SESSION_ID. A 401 indicates a token configuration problem; it does not prove ownership enforcement works.
Disabling enforcement restores store-wide access within the credential's grants. Keep backend authorization in place before disabling it. It does not remove stored owner fields, reassign records, or remove the need for store authentication.
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.
Workers authenticate with Kubernetes projected ServiceAccount tokens. The suite configures both
sides: it mounts the worker's token (workerAuth.enabled, memory.dataplane_client) and trusts
the worker's ServiceAccount, system:serviceaccount:<namespace>:redis-agent-memory-worker, in
memory.auth.worker_identity, against global.iris.workloadIdentity. Don't set these values
yourself: a differing value fails the render.
With a bring-your-own Data Plane configuration, add the dataplane_client and
auth.worker_identity blocks yourself, as in the
Data Plane configuration file.
The worker identity grants store access with resource keys such as mem-store:<store-id>, or
mem-store:* for a shared worker identity, with read, write, or full.
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.