Skip to main content
MemoryOS has two auth models:
  • Tenant API key — for /v1/memories/* and all workspace APIs
  • Cross-agent dual auth — for /v1/universal/*, which requires both an agent key and a user UUI token

​
Tenant API key

Authorization: ApiKey mem_...
All current keys use the mem_ prefix. The header format is exact — these all return AUTH_001: 
Authorization: mem_...
Authorization: Bearer mem_...
X-API-Key: mem_...
Keep your API key server-side. Never send it to the browser.

​
Cross-agent auth

Authorization: ApiKey agent_sk_...
X-MemoryOS-UUI: uui_...
Both headers are required for every universal memory call. agent_sk_... identifies the agent. uui_... identifies which Memory Passport user has granted access. Get your agent_sk_... key by registering 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 — it’s never shown again. If either header is missing or invalid, the API returns 403 UAT_001. A read-only grant attempting a write returns 403 UAT_002.

​
Identity model

Every tenant-scoped request combines tenant identity (from the API key) with end-user identity (from external_user_id in the request body): 
{ "external_user_id": "customer-123" }
One tenant safely stores memories for many users. Memories are isolated by (tenant_id, external_user_id). For cross-agent calls, identity is: agent (agent_sk_...) + user (uui_...) + scope (active PermissionGrant categories). The grant must be active and the requested category must be in categories_allowed. Human users manage their Memory Passport through the consent app using email + OTP — not raw uui_... tokens.

​
Common mistakes

MistakeErrorFix
Raw key without schemeAUTH_001Authorization: ApiKey mem_...
Bearer mem_...AUTH_001Authorization: ApiKey mem_...
Only one credential on /v1/universal/*UAT_001Send both agent_sk_... and uui_...
Revoked or expired grantEmpty retrieve resultRe-run the consent flow
Missing external_user_id on tenant routesREQ_422Always include it in write and retrieve requests
Key stored in browser codeSecret leakKeep MemoryOS keys server-side only

​
Key permissions

PermissionUse
readRetrieve memories and read list/export data
writeAdd memories and create extraction jobs
deleteDelete memories or run GDPR cleanup
adminBroad operational control

​
Security checklist

  • Load keys from environment variables
  • Use separate keys for dev, staging, and production
  • Rotate immediately if a key is exposed
  • Never commit keys to source control
  • Never log uui_... tokens in analytics or error payloads
  • Treat agent_sk_... like any other backend secret

​
Quick example

import os
from memoryos import Memory

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

​
Related pages