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

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.

Related