Skip to main content
MemoryOS has two authentication models:
  • Workspace-scoped API auth for the standard /v1/memories/* and workspace dashboard APIs
  • Cross-agent auth for /v1/universal/*, where both an agent key and a user UUI token are required
Human users do not sign in with raw UUI tokens. The consent app uses email plus OTP and then sends a signed MemoryOS session token to backend consent endpoints.

​
Tenant API key format

Send your API key in the Authorization header: Create a MemoryOS tenant API key in the dashboard 
Authorization: ApiKey mem_...
Current MemoryOS keys are generated with the mem_ prefix.
Use exactly this header format: 
Authorization: ApiKey mem_...
Wrong examples that trigger AUTH_001: 
Authorization: mem_...
Authorization: Bearer mem_...
X-API-Key: mem_...

​
Cross-agent auth format

For the universal memory APIs, send two credentials together: 
Authorization: ApiKey agent_sk_...
X-MemoryOS-UUI: uui_...
  • agent_sk_... identifies the agent making the request
  • uui_... identifies the user who granted or denied access
The agent_sk_... key is created when your workspace registers a global agent: 
POST /v1/agents/global
Authorization: ApiKey mem_...
The response includes raw_agent_api_key once. Store it in your backend secret manager or environment variables. If either header is missing or invalid, the universal APIs return:
  • 403
  • code: UAT_001
If the agent has read-only access and attempts a write, MemoryOS returns:
  • 403
  • code: UAT_002

​
Identity model

Every request combines:
  • Tenant identity from the API key
  • End-user identity from external_user_id
Example: 
{
  "external_user_id": "customer-123"
}
This lets one tenant safely store and retrieve memories for many different users. For cross-agent memory sharing, the identity model is different:
  • Agent identity comes from agent_sk_...
  • User identity comes from uui_...
  • Permission scope comes from the active grant between that user and that agent
For human consent and manage screens:
  • Human identity comes from email plus OTP
  • Consent session comes from a signed session token
  • Agent API calls still use agent_sk_... plus uui_...

​
Common authentication mistakes

MistakeWhat happensCorrect version
Sending the raw key onlyAUTH_001 unauthorizedAuthorization: ApiKey mem_...
Using Bearer mem_...AUTH_001 unauthorizedAuthorization: ApiKey mem_...
Calling /v1/universal/* with only one credentialUAT_001 cross_agent_auth_failedSend both Authorization: ApiKey agent_sk_... and X-MemoryOS-UUI: uui_...
Using a revoked or expired UUI grantUniversal retrieve returns no memories or write is deniedRe-run the consent flow to create an active grant
Asking users to remember raw uui_... tokensUsers lose access or get confusedUse email plus OTP in the consent app
Forgetting external_user_id on tenant routesREQ_422 or tenant resolution errorsAlways include external_user_id in write and retrieve requests
Reusing a key from the wrong tenantData is scoped to the wrong workspaceUse one API key per tenant/workspace
Storing the key in browser codeSecret leaks to clientsKeep MemoryOS API keys server-side

​
Key permissions

API keys store a permissions array. Current integrations commonly use these values:
PermissionIntended use
readRetrieve memories and read list/export data
writeAdd new memories and create ingestion jobs
deleteDelete memories or perform GDPR-style cleanup operations
adminInternal or operational actions where a key needs broad control

​
Cross-agent permission model

Agent API keys do not automatically grant access to user memories. For universal memory access, all of the following must be true:
  1. the agent is active
  2. the user exists and has a valid uui_... token
  3. the user granted this specific agent access
  4. the memory category being accessed is inside categories_allowed

​
Security best practices

Keep MemoryOS API keys on the server only.
  • Load them from environment variables
  • Rotate keys if they are exposed
  • Use separate keys for dev, staging, and production
  • Never commit keys to source control
  • Never send MemoryOS API keys to the browser
  • Never log uui_... tokens in analytics or frontend error payloads
  • Treat agent_sk_... keys like any other server-side credential

​
Example

​
Python

import os

from memoryos import Memory

client = Memory(api_key=os.environ["MEMORYOS_API_KEY"])

​
TypeScript

import { MemoryOS } from "@memoryos/sdk";

const client = new MemoryOS(process.env.MEMORYOS_API_KEY!);

​
Related pages