Authentication

Memex supports three auth modes:

OAuth for clients that complete a browser-based sign-in flow
API keys for direct REST, Claude Code, raw MCP clients, and local scripts
Supabase session JWTs for first-party Memex web, extension, and mobile traffic

Checkout at https://memex.garden/api/checkout uses Memex bearer auth. Send the same bearer token the agent uses for authenticated Memex requests.

Choose the right auth flow

OAuth

Use OAuth when the client expects a browser-based sign-in flow and sends bearer tokens after authorization. Memex publishes:

auth server metadata at https://memex.garden/api/.well-known/oauth-authorization-server
public API protected resource metadata at https://memex.garden/api/.well-known/oauth-protected-resource
MCP protected resource metadata at https://memex.garden/api/.well-known/oauth-protected-resource/mcp

OAuth scopes:

api:read
api:write

After sign-in, Memex accepts the OAuth access token as:

Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN

OAuth bearer tokens work on authenticated public API endpoints and on https://memex.garden/api/mcp when the granted scopes are sufficient.

API key

Use API keys for:

direct REST calls
the Codex plugin bundle
local Claude Code setups
raw MCP clients that can send custom headers or query parameters
local scripts and hooks

For REST, send the API key in the X-Api-Key header:

X-Api-Key: YOUR_MEMEX_API_KEY

For raw MCP clients, send the API key as a query parameter or custom header. userId is optional when you already have it:

https://memex.garden/api/mcp?apiKey=YOUR_MEMEX_API_KEY
https://memex.garden/api/mcp?userId=YOUR_USER_ID&apiKey=YOUR_MEMEX_API_KEY

X-Api-Key: YOUR_MEMEX_API_KEY
X-User-Id: YOUR_USER_ID

The Claude Code bundle also accepts:

export MEMEX_BEARER_TOKEN="YOUR_OAUTH_ACCESS_TOKEN"

That is optional. It lets a local Claude Code setup reuse an existing bearer token without copying API-key headers into the plugin config.

Supabase session JWT

First-party Memex browser, extension, and mobile clients can also use:

Authorization: Bearer YOUR_SUPABASE_SESSION_JWT

Human setup

Sign up or sign in at https://memex.garden/auth.
Open https://memex.garden/dashboard?settings.
Go to MCP server.
Click Generate Key if needed, then copy your API Key.
Reuse that key for direct REST calls, Claude Code, raw MCP clients, OpenClaw, and copyable skills.

Example REST request:

curl -X POST "https://memex.garden/api/search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_MEMEX_API_KEY" \
  -d '{
    "query": "vector databases",
    "limit": 5
  }'

Agent setup

If you are writing an agent workflow that stores long-lived credentials, use this order:

Check whether MEMEX_API_KEY is already stored in the agent config.
If it is missing, ask the human for their existing Memex API key first.
If the API key is not available, leave it empty and ask the human for an email address so you can sign up on their behalf.
If your runtime has access to x-agent-service-token, call POST https://memex.garden/api/agent-create-user.
Return the new apiKey to the human and store it in the agent config for future runs.
If your runtime does not have x-agent-service-token, send the human to https://memex.garden/auth, then ask them to copy API Key from Settings -> MCP server.

Suggested empty config shape before prompting:

{
    "MEMEX_API_KEY": ""
}

This endpoint is for agent runtimes that have the service token:

curl -X POST "https://memex.garden/api/agent-create-user" \
  -H "Content-Type: application/json" \
  -H "x-agent-service-token: YOUR_AGENT_SERVICE_TOKEN" \
  -d '{
    "targetUserEmail": "[email protected]",
    "targetUserName": "Optional display name",
    "targetUserPicture": "https://example.com/avatar.png"
  }'

Success response:

{
    "userEmail": "[email protected]",
    "isNewUser": true,
    "apiKey": "new-api-key",
    "recoveryHint": "To recover/get API key later, open memex.garden/auth and reset their password; then generate key in Settings."
}

Already-existing account response:

{
    "error": "USER_ALREADY_EXISTS",
    "message": "A user account already exists for this email.",
    "userEmail": "[email protected]",
    "recoveryHint": "To recover/get API key later, open memex.garden/auth and reset their password; then generate key in Settings."
}

Troubleshooting

Claude plugin redirects to localhost and Safari cannot connect: return to Claude and retry the plugin connection. The local callback only works while Claude is waiting for the OAuth result.
Codex or local Claude Code setup is missing credentials: export MEMEX_BEARER_TOKEN or MEMEX_API_KEY before launching the client.
Missing or stale API key: regenerate the key in Settings -> MCP server.
401 Unauthorized or Authentication required: verify that the bearer token or API key matches the auth mode expected by that client.
401 Unauthorized from /checkout: send the same Memex API key or OAuth bearer token the agent uses for MCP.
Next step after auth: Available endpoints
If the response says credits are exhausted: Buy credits

General

API reference

Plugins

Choose the right auth flow

OAuth

API key

Supabase session JWT

Human setup

Agent setup

Troubleshooting

​Choose the right auth flow

​OAuth

​API key

​Supabase session JWT

​Human setup

​Agent setup

​Agent signup request

​Troubleshooting

Choose the right auth flow

OAuth

API key

Supabase session JWT

Human setup

Agent setup

Agent signup request

Troubleshooting