Authentication

How tenant API keys, agent API keys, and UUI tokens work in MemoryOS.

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

Mistake	Error	Fix
Raw key without scheme	AUTH_001	Authorization: ApiKey mem_...
Bearer mem_...	AUTH_001	Authorization: ApiKey mem_...
Only one credential on /v1/universal/*	UAT_001	Send both agent_sk_... and uui_...
Revoked or expired grant	Empty retrieve result	Re-run the consent flow
Missing external_user_id on tenant routes	REQ_422	Always include it in write and retrieve requests
Key stored in browser code	Secret leak	Keep MemoryOS keys server-side only

Key permissions

Permission	Use
read	Retrieve memories and read list/export data
write	Add memories and create extraction jobs
delete	Delete memories or run GDPR cleanup
admin	Broad 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

Python

import os
from memoryos import Memory

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

Related pages

• Memory Passport
• Cross-agent memory sharing
• Python SDK reference