Skip to main content
The generally available MemoryOS API uses tenant API keys. A separate cross-agent model remains documented only for private-beta compatibility:
  • Tenant API key — for /v1/memories/* and all workspace APIs
  • Cross-agent dual auth (private beta) — disabled by default for /v1/universal/*

​
Tenant API key

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

​
Cross-agent auth

Cross-agent authentication is part of the frozen Memory Passport private beta. Registration and Universal Memory endpoints return 404 memory_passport_not_available unless MemoryOS explicitly enables the feature.
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:
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):
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

​
Key permissions

Permissions are enforced by the API on every tenant API-key request. admin includes all permissions. New keys default to read + write; create a separate key with delete or admin only for the backend process that needs those operations. The key’s configured rate_limit_per_minute is also enforced per key. Do not rely on the label alone as documentation—the stored permission list is the authorization boundary.

​
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