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
MCP server connections from AI agents (Claude Code, Codex, etc.)
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 or MCP config, use a Bearer token:

bash

curl -X POST https://your-instance.mnotes.app/api/mcp \
  -H "Authorization: Bearer mnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list"}'

In MCP config files, the key goes in the headers object:

.mcp.json

{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "https://your-instance.mnotes.app/api/mcp",
      "headers": {
        "Authorization": "Bearer mnk_your_api_key_here"
      }
    }
  }
}

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 or MCP setups that used the old key. See Agent Connect for re-configuring agent connections.