Authentication and API keys

Every request to /v1 and /mcp needs an API key, sent as a Bearer token or in the X-API-Key header. This page covers the key format, rotation, what the sandbox allows and how to keep keys safe.

How do I send my API key?#

Use either header. They are equivalent; if both are present, Authorization wins.

Headers
GET /v1/signals HTTP/1.1
Host: app.disruptapi.com
Authorization: Bearer dk_live_...

Keys are never accepted in the query string. The only /v1 routes that work without a key are GET /v1/plans, GET /v1/public/status and GET /v1/public/gnss-interference.

Check a key
curl "https://app.disruptapi.com/v1/me" \
  -H "Authorization: Bearer $DISRUPT_KEY"

What does a key look like?#

A key is dk_live_ followed by 32 random letters and digits. It is shown once, when you create it in the console. DisruptAPI stores only a SHA-256 hash and the first 14 characters, which the console shows so you can tell keys apart. If you lose a key, create a new one.

There is a single key type. There are no separate test keys or test hosts: a Sandbox key reads the same live data as a paid key, with smaller limits.

What happens when authentication fails?#

StatusCodeCause
401missing_api_keyNo Authorization: Bearer and no X-API-Key header.
401invalid_api_keyThe key is unknown, revoked, or its organisation has been disabled. Keys that do not start with dk_live_ are always invalid.
Response (401)JSON
{
  "error": {
    "code": "invalid_api_key",
    "message": "this API key is not valid or has been revoked"
  }
}

The MCP endpoint answers a missing or bad key with HTTP 401, a JSON-RPC error and a WWW-Authenticate: Bearer header. See MCP server.

How do I rotate a key?#

Keys do not expire. Rotate them on a schedule and whenever someone who had access leaves. Keys are managed in the console only; there is no API for creating or revoking keys.

  1. Create a second key in the console. An organisation can hold up to 20 active keys.
  2. Deploy the new key to your services and confirm traffic with GET /v1/me, which returns the key's id and name. The console shows when each key was last used.
  3. Revoke the old key. Revocation takes effect on the next request: the old key gets 401 invalid_api_key.

Rate limits, quotas and daily record budgets are counted per organisation, across all its keys, so adding keys does not add capacity. Name keys by service or environment (for example booking-api-prod) so usage by key is readable in GET /v1/usage.

Sandbox and paid plans#

New organisations start on the Sandbox plan (id free), which is meant for trying the API. Exposure checks and forecasts are included on every plan. The limits by plan, from GET /v1/plans:

PlanRequests a monthPer minuteWatched itemsWebhooksMax page sizeRecords a day
Sandbox (free)100105050500
Starter (starter)50,000602,500320050,000
Pro (pro)500,00030050,00020500500,000
Enterprise (enterprise)Unlimited1,200Unlimited100500Unlimited

Upgrades are made in the console and apply to existing keys right away. Rate limits and quotas explains how each limit is counted.

How should I keep keys safe?#

  • Server side only. Do not put a key in browser JavaScript, a mobile app or anything you ship to users. Call DisruptAPI from your backend and pass on only what users need. There is no CORS access to /v1 for browsers.
  • Secrets manager or environment variables. Never commit keys. The examples in these docs read DISRUPT_KEY from the environment.
  • One key per service and environment, so you can revoke one without touching the others.
  • Keep keys out of logs. Redact the Authorization and X-API-Key headers in request logging and error trackers.
  • MCP clients: put the key in an environment variable the client reads, not in a config file you share. See Connect a client.
  • If a key leaks, create a replacement and revoke the leaked key in the console. Then check GET /v1/usage for traffic you do not recognise.

Last updated 2026-11-18. Questions or a mistake on this page? Contact us.