Authentication and access¶
BreachSpider accepts three kinds of credentials. Which one you use decides which endpoints you can call.
| Credential | Sent as | Used by |
|---|---|---|
Session cookie (bs_session) | Set when you sign in with an email link | The web app |
API key (bs_live_...) | Authorization: Bearer bs_live_... | Your systems, the Python SDK, the local MCP server |
| Hosted MCP connection | OAuth access token, handled by your assistant | Assistants connected to https://mcp.breachspider.com/mcp |
A demo token (bs_demo_..., from breachspider.Client.demo() or the local MCP server with no key) gives read-only access to public example data only.
API keys¶
curl -H "Authorization: Bearer $BREACHSPIDER_API_KEY" \
"https://breachspider.com/api/v1/cves/CVE-2024-9137"
- Format:
bs_live_followed by 64 hex characters. Shown once when made; BreachSpider stores only a SHA-256 hash and the first 16 characters for display. - Scopes:
read, orreadandwrite. A read key that tries to change something gets403withinsufficient_scope. - Expiry: 30, 90 or 365 days, or none. An expired or revoked key gets
401on every endpoint, v1 and v2. - Send keys only in the
Authorizationheader, never in a URL, and keep them in environment variables.
Where keys come from¶
| Account | How you get a key | What the key can call |
|---|---|---|
| Customer plans with API access (Professional and above) | Make it on Integrations in the web app | The read surface of the API; write endpoints with a write key |
| Free API trial (14 days) | breachspider.com/developers | POST /api/v1/assets/correlate-cves, POST /api/v1/assets/correlate-cves/check and GET /api/v1/cves/{id}; read only; 750 device checks, 25 devices per call |
| API partner | Issued by BreachSpider | The device API, its change check, the CVE endpoints and the stateless Windows check; with a write key also the Windows API (v2) and the environments it uses; batch jobs when enabled for the key |
Prices are not published: every customer plan is arranged individually. Ask through breachspider.com/contact.
Session-only operations¶
Some operations need a person signed in to the web app and refuse every API key, even a write key (403, session_required): creating, listing and revoking API keys; creating and changing webhooks; billing; account and team changes; two-factor setup; the documents vault and workspace backups. This keeps a leaked key from creating more keys or redirecting alerts.
Web app sign-in¶
The web app signs in with a link emailed to you (no passwords), valid once for 60 minutes, plus an authenticator code when two-factor sign-in is on. The session cookie is HttpOnly, Secure and SameSite=Lax and lasts up to 30 days. See Security model.
Limits¶
Per-key, per-address and monthly allowances are described in Rate limits and usage.