API Keys

API keys provide an alternative to OAuth for authenticating with Basic Memory Cloud. Use them for CLI tools, automation scripts, or any MCP client that supports bearer token authentication.

Why Use API Keys?

• Simpler setup - No OAuth flow required
• Automation friendly - Use in scripts and CI/CD
• Multiple keys - Create separate keys for different tools
• Revocable - Disable a key without affecting others

Creating an API Key

Using API Keys

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "basic-memory": {
      "url": "https://cloud.basicmemory.com/mcp",
      "headers": {
        "Authorization": "Bearer bmc_your_key_here"
      }
    }
  }
}

With Codex CLI

Add to ~/.codex/config.toml:

[[mcp_servers]]
name = "basic-memory"
url = "https://cloud.basicmemory.com/mcp"
bearer_token_env_var = "BASIC_MEMORY_API_KEY"

Then set the environment variable:

export BASIC_MEMORY_API_KEY=bmc_your_key_here

With Other MCP Clients

Any MCP client that supports HTTP headers can use API keys:

Authorization: Bearer bmc_your_key_here

With curl

Test your key with curl:

curl -H "Authorization: Bearer bmc_your_key_here" \
  https://cloud.basicmemory.com/api/v2/projects

Managing Keys

View Your Keys

In Settings → API Keys, you'll see:

• Key name
• Key prefix (first few characters for identification)
• Creation date
• Last used timestamp
• Status (active/expired/revoked)

Revoking a Key

To disable a key:

1. Go to Settings → API Keys
2. Find the key you want to revoke
3. Click Revoke
4. Confirm the action

Revoked keys stop working immediately. This cannot be undone.

Security Best Practices

Do

• Use descriptive names - "Claude Desktop Work" is better than "key1"
• Set expiration dates - Especially for temporary access
• Use environment variables - Don't hardcode keys in config files
• Revoke unused keys - Clean up keys you no longer need
• Create separate keys - One per device or application

Don't

• Share keys - Each user should have their own account and keys
• Commit keys to git - Add config files with keys to .gitignore
• Use keys in URLs - Always use the Authorization header
• Ignore suspicious activity - Check "last used" timestamps regularly

Key Format

API keys follow this format:

bmc_<random-base64url-string>

• Prefix bmc_ identifies it as a Basic Memory Cloud key
• 32 bytes of cryptographically random data
• URL-safe base64 encoding

Example: bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv

API Keys vs OAuth

Use API keys for:

• Command-line tools
• Automation scripts
• Headless environments
• Multiple concurrent sessions

Use OAuth for:

• Web applications
• First-time setup in Claude/ChatGPT
• When you want automatic token refresh

Troubleshooting

Key Not Working

1. Verify the key is copied correctly (no extra spaces)
2. Check the key hasn't been revoked
3. Check the key hasn't expired
4. Ensure the Authorization header format is correct: Bearer bmc_...

"Unauthorized" Error

1. Confirm your subscription is active
2. Verify the key belongs to your account
3. Try creating a new key

Key Not Showing in List

Keys are only shown once at creation. If you lost the key:

1. Revoke the old key
2. Create a new one
3. Update your configuration

Next Steps