Authentication

MemoryRouter uses a two-key system: your Memory Key authenticates with MemoryRouter, and your Provider Keys authenticate with AI providers.

Memory Key (`mk_xxx`)

A Memory Key is an API credential for MemoryRouter. In multi-user products, it identifies one user-scoped memory vault and tracks usage for that vault.

Get your key: app.memoryrouter.ai → API Keys

Usage

Standard (Authorization header):

curl -X POST https://api.memoryrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-5.5", "messages": [...]}'

Anthropic SDK style (x-api-key):

curl -X POST https://api.memoryrouter.ai/v1/chat/completions \
  -H "x-api-key: mk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-opus-4.8", "messages": [...]}'

Provider Keys

Your actual API keys for OpenAI, Anthropic, Google, etc. Two options:

Option 1: Store in Dashboard (Recommended)

Go to app.memoryrouter.ai → Settings
Add your provider keys (encrypted at rest)
Just use your Memory Key, MemoryRouter handles the rest

client = OpenAI(
    api_key="mk_xxx",
    base_url="https://api.memoryrouter.ai/v1"
)

Option 2: Pass-Through Mode (BYOK)

Send your provider key with each request. The key is never stored. It's used for that one request and discarded. There are two equivalent, fully supported ways to send it. Both behave identically; pick whichever fits your client.

Method A, Drop-in (recommended): provider key in Authorization, Memory Key in X-Memory-Key. Best when pointing an existing provider SDK at MemoryRouter.

curl -X POST https://api.memoryrouter.ai/v1/chat/completions \
  -H "X-Memory-Key: mk_xxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-5.5", "messages": [...]}'

client = OpenAI(
    api_key="sk-your-openai-key",  # Goes to provider
    base_url="https://api.memoryrouter.ai/v1",
    default_headers={
        "X-Memory-Key": "mk_xxxxxxxxxxxxxxxx"  # MemoryRouter auth
    }
)

Method B, Explicit header: provider key in X-Provider-Key, Memory Key in Authorization. Best when you'd rather keep Authorization as your MemoryRouter credential and pass the provider key in its own dedicated header.

curl -X POST https://api.memoryrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxx" \
  -H "X-Provider-Key: sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-5.5", "messages": [...]}'

Methods A and B are two paths to the same result, not a fallback or a guess. Use A for drop-in SDK compatibility, B when you want the provider key in a clearly-named header.

Authentication Headers Summary

Header	Purpose	When to Use
`Authorization: Bearer mk_xxx`	Memory Key auth	Standard usage
`x-api-key: mk_xxx`	Memory Key auth	Anthropic SDK compatibility
`X-Memory-Key: mk_xxx`	Memory Key auth	Pass-through mode
`Authorization: Bearer sk-xxx`	Provider key	Pass-through mode
`X-Provider-Key: sk-xxx`	Provider key	Alternative pass-through

Key Mode Suffixes

Append a mode suffix to any memory key to control memory behavior at the connection level, no headers or code changes needed.

Key	Effect
`mk_xxx`	Normal, read and write memory (default)
`mk_xxx:read`	Retrieve memories but don't store new ones
`mk_xxx:write`	Store conversations but don't retrieve memories
`mk_xxx:off`	No memory, pure proxy pass-through

The suffix is stripped before authentication. mk_abc123:read authenticates as mk_abc123 with read-only memory.

Use case: Set up two connections in Open WebUI, one with mk_xxx for full memory, one with mk_xxx:read for querying without storing. Same key, different behavior.

Multiple Memory Keys

Create separate keys for different apps, customers, or end users. Each key has isolated memory.

# App 1
app1_client = OpenAI(api_key="mk_app1_xxx", base_url="https://api.memoryrouter.ai/v1")

# App 2 (completely separate memory)
app2_client = OpenAI(api_key="mk_app2_xxx", base_url="https://api.memoryrouter.ai/v1")

Error Responses

401 - Missing authentication:

{"error": "Missing or invalid authentication", "hint": "Use: Authorization: Bearer mk_xxx"}

400 - Missing provider key:

{"error": "No API key configured for provider: openai", "hint": "Add your openai API key in settings, or pass X-Provider-Key header"}

Authentication

On this page