Skip to main content

Authentication

API Keys​

All programmatic access uses API keys. Get one from Settings → Developer in the DialogBrain app.

Using Your Key​

Every request to the REST API requires the X-API-Key header:

# REST API
curl https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: db_live_YOUR_KEY_HERE"

The same key works with the Python SDK:

from dialogbrain import DialogBrainClient

async with DialogBrainClient(api_key="db_live_YOUR_KEY_HERE") as client:
    agents = await client.agents.list()

And with the MCP server (e.g., in Claude Code or Cursor):

claude mcp add dialogbrain https://api.dialogbrain.com/mcp/
# (Or set the environment variable: export DIALOGBRAIN_API_KEY=db_live_YOUR_KEY_HERE)

Key Properties​

  • Scope: Each key is tied to exactly one workspace. It grants access only to resources within that workspace.
  • Format: db_live_<random> (production) or db_test_<random> (test)
  • Foreign resources answer 404: If your key is from workspace A and you try to access a resource from workspace B, the API returns 404 Not Found — the same response as a truly missing resource.
  • Workspace locking in MCP: The workspace_locked property governs whether MCP clients can switch workspaces. If workspace_locked: true, the MCP server will only serve that workspace's resources and refuse workspace-switching tokens.

Rotation​

To rotate a key without downtime:

  1. Create a new key in Settings → Developer
  2. Update your application to use the new key
  3. Verify the application works
  4. Revoke the old key (it stops working immediately)

Security​

  • Never embed keys in client-side code — the key grants full API access to your workspace
  • Use environment variables for local development and deployment
  • Revoke compromised keys immediately

MCP Server OAuth​

MCP clients (Claude Code, Cursor, VS Code) use OAuth 2.0 — you authenticate via browser without hardcoding keys:

{
  "mcpServers": {
    "dialogbrain": {
      "url": "https://api.dialogbrain.com/mcp/"
    }
  }
}

The MCP server also accepts X-API-Key for programmatic access (e.g., langchain-mcp-adapters) and respects the workspace_locked setting.

JWT Bearer (Internal Use)​

The DialogBrain web app uses short-lived JWT access tokens. Webhook endpoints also accept Bearer tokens so the frontend can manage webhooks without an API key.

See also: Workspace scoping