Authentication

API keys — REST API

Get your API key from Dashboard → API Keys. Pass it in every request using either the X-Api-Key header (recommended) or a Bearer token:

Option 1 — X-Api-Key header (recommended)

X-Api-Key: YOUR_API_KEY

Option 2 — Authorization: Bearer

Authorization: Bearer YOUR_API_KEY

Both methods are equivalent. Use X-Api-Key when your HTTP client or framework makes it easier to set a plain header. Use Authorization: Bearer for compatibility with tools that expect the standard HTTP auth header.

Key prefixes

Prefix	Type	Used with
cl_live_	REST API key — production	REST API (`X-Api-Key` or Bearer)
cl_test_	REST API key — sandbox	REST API (`X-Api-Key` or Bearer)
st_live_	Service token — Agent plans	MCP server (Bearer only) — for automated pipelines

OAuth — MCP server

The MCP server uses OAuth 2.0 rather than API keys. This gives your AI agent user-delegated access — it acts on behalf of your account without you embedding a long-lived secret in a config file.

The first time your MCP client connects to https://mcp.companylens.io/mcp:

Your client discovers the OAuth server via the MCP metadata endpoint.
A browser window opens for you to log in to CompanyLens.
After login, the access token is stored by your client — you won't be prompted again until it expires.

Clients that support Dynamic Client Registration (DCR) — including Claude Desktop — handle this automatically. Others use the standard authorization code flow.

Service tokens — Agent plans

Service tokens let automated pipelines call the MCP server without an interactive OAuth browser flow. They are available on Agent Starter and Agent Pro plans.

Create a service token in Dashboard → Service Tokens. The plaintext token is shown once at creation — copy it immediately. Pass it as a standard Bearer header on every MCP request:

Authorization: Bearer st_live_…

Service tokens use a separate monthly quota from your OAuth session — service-token calls do not consume your daily OAuth allowance and vice versa. See rate limits for quota details.

Plan	Tokens	Service-token monthly quota
Agent Starter	1	5,000 calls / month
Agent Pro	Up to 5	25,000 calls / month

Security

Never expose your API key or service token in client-side code — it will be visible in browser DevTools.
Rotate REST API keys from Dashboard → API Keys — the old key is invalidated immediately.
Revoke service tokens from Dashboard → Service Tokens — revocation takes effect immediately.
Keys and tokens are scoped to your account. There are no per-endpoint restrictions.

Troubleshooting

Symptom	Likely cause	Fix
401 on every request	Key copied with trailing whitespace	Re-copy the key; check for extra spaces
401 after previously working	Key rotated or revoked	Generate a new key in the dashboard
401 with correct key	Wrong header format	Use `X-Api-Key: YOUR_KEY` or `Authorization: Bearer YOUR_KEY`
403 on a specific endpoint	Plan doesn't include this endpoint	Upgrade or check pricing

Ready to make your first call? Quickstart → Or see what happens when auth fails: API troubleshooting →

Documentation