Authentication & Scopes
Bearer token authentication, key scopes, and least-privilege key design.
Bearer token authentication
Every request must include an Authorization header:
Authorization: Bearer YOUR_API_KEY
No or an unknown key: HTTP 401. A key without the scope the request needs: HTTP 403. Most endpoints answer 403 with an error naming the missing scope; some also include "code": "API_KEY_SCOPE" and the scope in required. Your organization's allowed IP ranges (Settings → Security policy) apply to keys too.
API key scopes
Scopes are <area>:read or <area>:write. Write includes read for the same area. Give each key the fewest it needs:
- Scope — What it allows
- servers:read — List servers and their details
- metrics:read — Metric history
- processes:read — Running processes
- alerts:read — List alerts; Cortex plans
- alerts:write — Acknowledge one alert at a time
- audit:read — The audit log and its export
- fleet:read — Fleet summary and status
- compliance:read — Compliance scores and findings
- cve:read — The CVE board and each server's vulnerability findings
- rules:read / rules:write — Read / change rules and incoming event sources
- webhooks:read — List webhook endpoints and deliveries
- webhooks:write — Rotate an endpoint's secret, replay a delivery
- events:read / events:write — Read / push custom events
- stream:read — The live event stream
- actions:write — Ban or unban IPs, run scans, lock down, restart the agent, approve Cortex steps
- read:* / write:* — Every area for that operation
Whatever its scopes, no key can reach anything outside this API: not the vault, terminals, members, billing, settings, other keys, or bulk alert acknowledgement. Those need a person signed in.
Key rotation
An org owner rotates a key from Developer → API Keys or with POST /api/v1/keys/:keyId/rotate (signed in, not with a key). The old secret stops working within 15 seconds; there is no grace period beyond that. The new one is shown once.
For zero-downtime rotation: create a new key, switch your integration to it, check it works, then revoke the old one.
Webhook signature verification
Deliveries carry X-Watch-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body keyed with the endpoint's secret. See API: Webhooks → Signature verification for working code. The body's own ts is signed; the X-Watch-Timestamp header is not. (The X-Watch- names come from the product's earlier name.)
Tips
- Never log API keys — treat them like passwords.
- Create a separate key per integration so you can revoke one without affecting others.
- Restrict your organization's allowed IP ranges (Settings → Security policy) — keys are held to them too.