Skip to content
English
  • There are no suggestions because the search field is empty.

Authenticate your API requests

Summary

Every REST API request authenticates with a single header carrying your API key. This article covers how that works, what a rate limit looks like in practice, and how to read the errors you'll get back when something's wrong.

Before you start

You'll need an API key, see Connect an integration if you haven't created one yet.

1. Send your key on every request

Include your key in the X-API-Key header on every request to /api/public/v1/.... There's no Bearer-token form for the REST API: only this header is accepted.

GET /api/public/v1/events
X-API-Key: <your key>

2. Watch your rate limit

Every authenticated response carries two headers:

  • X-RateLimit-Limit: your key's per-minute cap. New keys default to 120 requests per minute; you can raise this (up to 6,000) when creating a key.
  • X-RateLimit-Remaining: how many requests you have left in the current one-minute window.

If you exceed your limit, you'll get a 429 response with a Retry-After header telling you how many seconds to wait before trying again.

3. Handle the error responses

  • 401 Unauthorized: the X-API-Key header is missing, or the key is invalid or no longer active because it was revoked, rotated, or passed its expiry date. There's no partial credit here: check the header is present and you're sending the current key before anything else.
  • 403 Forbidden with "Insufficient scope" in the body: your key is valid, but it doesn't carry the scope this endpoint requires. The response names the missing scope directly. See Choose the right API key scopes.
  • 403 Forbidden for an organization that de-identifies activity: your key and its scopes are fine. The request tried to filter or identify a specific person, and your organization doesn't share who did what through the API, and the response body says so. Change the request rather than the key: rotating or re-scoping a key will not clear this. See Explore the REST API reference.
  • 403 Forbidden naming a required feature (upgrade_required): your plan does not include this endpoint's module. The body's message says which, for example "Incident Response Hub isn't included in your plan.", and usually also gives featureName and your currentTier. Changing the key will not clear this. See Developer tools: integrate with CyberHQ.ai for the areas that need a higher plan.
  • 403 Forbidden saying the license is inactive (license_inactive): your organization's license has lapsed or is invalid. Changing the key, its scopes, or retrying does not help: your administrator must renew it.
  • Several different conditions return 403, so read the response body before acting on any of them.
  • 409 Conflict with policy_type_exists when creating or updating an alert policy: some alert types allow only one policy for the whole organization, because their thresholds apply organization-wide. The body names the existing policy; update that one instead.
  • 429 Too Many Requests: you've exceeded your rate limit for the current window. Respect the Retry-After header rather than retrying immediately.
  • 503 Service Unavailable: a transient failure resolving your subscription entitlement or an organization privacy setting, not a problem with your key or your subscription itself. The entitlement case carries a Retry-After header too: retry with backoff rather than treating either as a hard failure.

Confirm it worked

A successful request returns your data along with the two rate-limit headers. If you're unsure whether your key is valid at all, a request to any endpoint your key is scoped for is the simplest test: a 401 means the key itself is the problem, not the specific endpoint.

If it didn't work

  • Getting 401s on a key that used to work: check whether it has passed its expiry date, or whether someone rotated or revoked it, under Settings → Integrations → API keys. Rotating replaces the key immediately, so every system still sending the old key fails exactly as if the key were invalid. Update them with the new key.
  • 429s under normal-looking traffic: your rate limit may be lower than your integration needs; create a new key with a higher limit rather than adding client-side retries as the primary fix.
  • 403 on an endpoint that used to work: several causes. Scopes are set when a key is created, so confirm the key you're sending carries the scope the endpoint requires. If the scopes are unchanged, check whether your organization de-identifies activity, whether your plan includes the endpoint, and whether your organization's license is active: each of those refusals is also a 403, and the response body tells you which one you have.

Related