API Keys

API keys authenticate the mnotes CLI and MCP integrations with your m-notes instance. Each key is scoped to your account and provides full access to your workspaces.

What Are API Keys?

API keys are long-lived tokens that authenticate programmatic access to m-notes. They are used by:

The mnotes CLI for all commands
AI agent connections (Claude Code, Codex, Cursor, etc.) configured via mnotes connect
Direct HTTP requests to the m-notes API

Generating a Key

1Open Settings from the sidebar or user menu.
2Navigate to the API Keys section.
3Click Generate New Key. Give it a descriptive name (e.g., "Claude Code - project X").
4Copy the key immediately. It is only shown once and cannot be retrieved later.

Key Format

All API keys start with the mnk_ prefix, followed by a random alphanumeric string. Example:

mnk_a1b2c3d4e5f6g7h8i9j0...

The mnk_ prefix makes keys easy to identify in config files and secret scanners.

Using API Keys

There are three ways to provide your API key:

1. Command-line flag

Pass the key directly with the --api-key flag:

bash

mnotes list --api-key mnk_your_api_key_here

2. Environment variable

Set MNOTES_API_KEY so the CLI picks it up automatically:

bash

# Add to your shell profile (.bashrc, .zshrc, etc.)
export MNOTES_API_KEY="mnk_your_api_key_here"

# Or use a .env file in your project
echo 'MNOTES_API_KEY=mnk_your_api_key_here' >> .env

3. Authorization header

For direct HTTP requests to the m-notes API, use a Bearer token:

bash

curl -X POST https://your-instance.mnotes.app/api/v1/notes/search \
  -H "Authorization: Bearer mnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"test"}'

For AI clients, prefer mnotes connect — it writes the right config files for you so you never paste a key by hand:

bash

# Configure your AI client via the CLI (recommended)
mnotes connect claude-code \
  --url https://your-instance.mnotes.app \
  --api-key mnk_your_api_key_here \
  --workspace ws_your_workspace_id

Security Best Practices

Practice	Details
Never commit keys to git	Store keys in environment variables or `.env` files that are gitignored.
Use environment variables	Prefer `MNOTES_API_KEY` over hardcoding keys in config files.
Rotate periodically	Generate a new key and revoke the old one every 90 days, or immediately if compromised.
One key per integration	Use separate keys for each agent or project so you can revoke individually.

Make sure your .env files are gitignored:

.gitignore

# .gitignore
.env
.env.local

Revoking a Key

If a key is compromised or no longer needed:

1Open Settings and navigate to API Keys.
2Find the key you want to revoke and click Revoke.
3Confirm the revocation. The key stops working immediately across all integrations.

After revoking, update any CLI configs that used the old key. See CLI Connect for re-configuring AI client connections.