API & MCP
Authentication
API keys and OAuth 2.1 — how to authenticate against the Breaknorm API and MCP server.
Every request carries Authorization: Bearer <credential>. Two kinds of credential work everywhere — MCP
and REST — and both belong to an organization: its lists, exports, plan and usage.
API keys
Create keys in the dashboard under API keys. A key looks like bnk_live_… and is shown once; we
store only its hash. Give each client its own key and only the scopes it needs:
| Scope | Allows |
|---|---|
companies:read | search, count, lookalikes, segments, company records, lists (read), usage |
lists:write | create lists, add and remove companies |
exports:create | full-list exports, cancel jobs |
email:find | find e-mail addresses (single and bulk) |
email:verify | verify e-mail addresses |
Revoking a key takes effect immediately.
OAuth 2.1
Hosted assistants (claude.ai, Claude Desktop, ChatGPT) connect with OAuth — the person approves the app on app.breaknorm.co and, if they belong to several organizations, picks the one it acts for.
| Protected resource metadata | https://mcp.breaknorm.co/.well-known/oauth-protected-resource |
| Authorization server | https://app.breaknorm.co (/.well-known/oauth-authorization-server) |
| Client registration | dynamic (RFC 7591) or Client ID Metadata Documents |
| Flow | authorization code + PKCE (S256); send resource=https://mcp.breaknorm.co |
| Access token | JWT, 30 minutes, audience-bound, carries the organization |
| Refresh token | rotated on every use (with offline_access) |
Disconnect an app under Connected apps: its refresh tokens are revoked at once and its current access token expires within 30 minutes.
A request without a credential gets 401 with WWW-Authenticate: Bearer resource_metadata="…" — that is
the start of OAuth discovery, not an outage.