Skip to content

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, or read and write. A read key that tries to change something gets 403 with insufficient_scope.
  • Expiry: 30, 90 or 365 days, or none. An expired or revoked key gets 401 on every endpoint, v1 and v2.
  • Send keys only in the Authorization header, 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.