Choose the right API key scopes
Summary
An API key can only do what its scopes explicitly allow: there's no broader "admin" scope that grants everything. This article lists what's available so you can grant a key exactly what your integration needs, and nothing else.
Before you start
Scopes are chosen when you create a key (see Connect an integration) and stay fixed for the life of the key. To change them, create a new key with the scopes you need and revoke the old one.
The available scopes
| Scope | Grants |
| signals:read | Read signals (alerts, findings, and similar items from your triage queue) |
| signals:write | Acknowledge a signal, or mark it in progress. It cannot resolve, suppress or close one |
|
events:read |
Read activity event metadata: metadata only, never captured content |
| users:read |
Read your user roster and per-user activity summaries |
| assets:read |
Read your registered assets |
| compliance:read | Read compliance frameworks, controls, and attestations |
| policies:read | Read your alert policies |
| policies:write | Create, update, or delete an alert policy |
| incidents:read | Read incidents |
| incidents:write | Promote a signal to an incident, or resolve one |
| remediation:read | Read remediation actions |
| remediation:write | Transition or reassign a remediation action |
A scope never overrides your plan. Signals, compliance, incidents, remediation, and changing alert policies need the Professional plan. Compliance programs come with Ultimate or the Full compliance add-on, and also have to be turned on for your organization. A request to an area your plan doesn't include gets a 403 with upgrade_required, whatever scopes the key holds. See Developer tools: integrate with CyberHQ.ai.
Two things about keys, before you pick scopes
A key's scopes are independent of any user's role. A key is not a person: it neither inherits anyone's permissions nor is limited by them. The practical consequence is that removing a user does not disable keys they created: those have to be revoked separately.
A key's value is shown once, at creation or rotation, and never again. Copy it at that moment. If you lose it, rotate the key to get a new value: which also stops the old one working, so any integration still using it will break.
1. Work out what your integration actually needs
Most integrations need only a handful of these. A SIEM pulling activity data typically needs only events:read, which works on every plan, and signals:read, which needs the Professional plan. A ticketing sync that creates incidents from your own alerting needs incidents:write (and usually incidents:read alongside it, to check state before acting); incidents need the Professional plan.
2. Grant only those scopes
Select exactly the scopes you identified. There are 12 scopes in all, so a key can hold at most 12, though most integrations need far fewer. If your integration grows, create a new key with the extra scopes, so there's no cost to starting narrow.
3. Prefer read scopes unless you specifically need to write
If your integration only consumes data (a dashboard, a report, a SIEM feed), grant only the :read scopes it needs. Reserve :write scopes for integrations that genuinely take action back into the platform.
Confirm it worked
Make a request to an endpoint requiring one of the scopes you granted, and confirm it succeeds. Then make a request to an endpoint requiring a scope you deliberately didn't grant, and confirm you get a 403 naming that scope: this is the fastest way to verify your key is scoped exactly as intended.
If it didn't work
- Unknown scope error when creating a key: check the exact scope names above; they're case-sensitive and follow the resource:action pattern precisely.
- A working integration suddenly gets 403s: check the key's scope list against what your integration actually calls, including any endpoint it has started using since the key was created. If the scopes cover it, the refusal may be an organization that de-identifies activity, a plan that doesn't include the endpoint, or an inactive license instead. Each is also a 403 and is not fixed by re-scoping. The response body distinguishes them.
- Unsure whether to grant :write: when in doubt, don't. You can create a key with a write scope later, the moment you actually build the feature that needs it.