--- title: "API Keys" description: "Create API keys for programmatic access to Basic Memory Cloud without OAuth." canonical_url: "https://docs.basicmemory.com/cloud/api-keys" --- # API Keys > Create API keys for programmatic access to Basic Memory Cloud without OAuth. 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 ### Open Settings In the [web app](https://app.basicmemory.com), go to **Settings → API Keys** ### Click Create Key Keys are grouped by workspace. Click **Create Key** next to the workspace you want the key for, then confirm with **Create**. Only owners and admins can create keys. ### Name Your Key Enter a descriptive name like "Claude Desktop" or "Work Laptop". The name shows up in note attribution (see [Who wrote this note?](#who-wrote-this-note)), so name keys after the agent or device that uses them. ### Choose Read-only Access (Optional) - **Read-only** — the key can search and read notes but cannot create, change, or delete anything. Use it for agents that only need recall. This can't be changed after the key is created. A key acts as the member who created it and can never do more than that member can. ### Copy Your Key **Important:** Copy the key immediately. It's only shown once and cannot be retrieved later. The key looks like: `bmc_abc123def456...` Store your API key securely. Each key belongs to a specific workspace — anyone with the key can access that workspace. Never commit keys to version control or share them publicly. --- ## Using API Keys ### With Claude Desktop Claude Desktop connects to Basic Memory Cloud through its **Connectors** OAuth flow, not an API key — see [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop). If you specifically need bearer-token auth (for example on an account without browser OAuth), bridge through a stdio proxy in `claude_desktop_config.json`: ```json { "mcpServers": { "basic-memory": { "command": "npx", "args": [ "mcp-remote", "https://cloud.basicmemory.com/mcp", "--header", "Authorization: Bearer bmc_your_key_here" ] } } } ``` ### With Codex CLI Add to `~/.codex/config.toml`: ```toml [mcp_servers.basic-memory] url = "https://cloud.basicmemory.com/mcp" bearer_token_env_var = "BASIC_MEMORY_API_KEY" ``` Full walkthrough (key export, shell setup): [Codex integration](https://docs.basicmemory.com/integrations/codex). Then set the environment variable: ```bash export BASIC_MEMORY_API_KEY=bmc_your_key_here ``` ### With Other MCP Clients Any MCP client that supports HTTP headers can use API keys: ```text Authorization: Bearer bmc_your_key_here ``` ### With curl Test your key with curl: ```bash curl -H "Authorization: Bearer bmc_your_key_here" \ https://cloud.basicmemory.com/api/v2/projects ``` ### With Basic Memory CLI (per-project routing) Save a key for the CLI to use: ```bash # Save an existing key from the web app bm cloud api-key save bmc_your_key_here # Or create and save a new key (requires active OAuth session — run bm cloud login first) bm cloud api-key create "work-laptop" ``` The key authenticates cloud-routed projects — for routing projects through cloud (`bm project set-cloud` / `set-local`), see [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing). --- ## 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. If you suspect a key has been compromised, revoke it immediately and create a new one. --- ## Read-only keys A read-only key can run every read operation — search, read, `bm_context`, project status — and is refused on any write. Write tools (`bm_write`, `bm_edit`, `bm_move`, `bm_delete`) return an MCP tool error (`isError`) saying the key is read-only, so a client never mistakes a refused write for a saved one. Use Basic Memory v0.24 or later with read-only keys. Earlier CLI and local MCP versions checked project status with a `POST` request, so a read-only key could get "This API key is read-only" on an ordinary search that returned no results. --- ## Who wrote this note? When a note is created or updated through an API key, Basic Memory Cloud stamps `created_by` and `updated_by` into the note's frontmatter as ` via `: ```yaml --- title: Cache Layer Design created_by: Alice via Codex CLI updated_by: Bob via Claude Desktop --- ``` - The cloud sets these keys; any value a writer submits for them is overwritten. - `created_by` is set once and carried forward. Notes written before v0.24 don't gain one retroactively. - Moves and deletes don't restamp, and a write that doesn't change authorship doesn't rewrite the file. - Local installs supply no author, so they leave both keys untouched. --- ## Security Best Practices ### Do - **Use descriptive names** - "Claude Desktop Work" is better than "key1" - **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: ```text bmc_ ``` - 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
Feature API Keys OAuth
Setup Copy/paste key Browser-based flow
Best for CLI, scripts, automation Interactive apps
Token refresh No (long-lived) Yes (short-lived + refresh)
Revocation Per-key Per-session
Access Full access to the key's workspace, optionally read-only Full account access
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 Complete cloud setup and features overview. Set up Claude Desktop with Basic Memory. Command-line tools for Basic Memory. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.