Scopes & Access Planning

API keys in SonarSend belong to service accounts, not individual users.

Each key should receive only the scopes it actually needs.

How to think about scopes#

Use scopes to answer two questions:

1. what data can this integration read or modify
2. whether it can take execution-risk actions such as scheduling a send

The most important distinction for broadcast work is:

• broadcasts:write can create and update drafts
• broadcasts:schedule can test-send and schedule sends

Available scopes#

Broadcasts#

• broadcasts:read
• broadcasts:write
• broadcasts:schedule

Contacts and audience#

• contacts:read
• contacts:write
• lists:read
• lists:write
• segments:read
• segments:write

Sequences#

• sequences:read
• sequences:write

Content#

• templates:read
• templates:write

templates:* covers content blocks as well as templates, including the markdown import/export endpoints.

Reporting and events#

• reports:read — the three broadcast reporting endpoints: the summary report, per-link click stats, and bulk metrics
• events:write — record custom events. Reading events back is done in the app, so there is no events:read.

Deliverability and sender setup#

• sending-identities:read — sending identities and email types

Data model and compliance#

• custom-fields:read — read custom field definitions and their usage counts. There is no write side over the API; fields are defined in the app.
• suppression:read
• suppression:write

Full access#

• *

* grants all currently supported external API capabilities.

Every scope listed above unlocks at least one endpoint, and the list is exhaustive. If a capability is not here, it is not reachable with a key at all — there is no scope you can add to get it.

Scope inheritance#

For most domains, write also allows read.

Examples:

• a key with contacts:write can also list and read contacts
• a key with segments:write can also read dynamic segments
• a key with broadcasts:write can also read broadcasts

This does not apply to execution scopes.

Example:

• broadcasts:write does not include broadcasts:schedule

Recommended key patterns#

Content sync key#

Use when an external system creates or updates drafts, but SonarSend users handle final scheduling.

Suggested scopes:

• broadcasts:write
• lists:read
• segments:read
• sending-identities:read

Execution-capable broadcast key#

Use when the integration should create drafts and also schedule or test them.

Suggested scopes:

• broadcasts:write
• broadcasts:schedule
• lists:read
• segments:read
• sending-identities:read

CRM sync key#

Use when an external system maintains contact records.

Suggested scopes:

• contacts:read
• contacts:write
• custom-fields:read

Reporting key#

Use when a BI tool or warehouse job only needs metrics.

Suggested scopes:

• reports:read
• broadcasts:read — to list the broadcasts whose reports you then fetch
• contacts:read — only if the job also runs contact exports

Compliance key#

Use when another system needs to read or manage suppressions.

Suggested scopes:

• suppression:read
• suppression:write

What service-account keys cannot do#

Even a full-access API key is intentionally narrower than a logged-in admin session.

Service-account keys cannot be used for:

• user and admin account management
• API key management
• tenant settings and security actions
• advanced internal-only app routes that are not part of the public API

The app also keeps a number of capabilities to itself deliberately, rather than by omission: the detailed reporting views behind a broadcast’s report page, a contact’s event history and the account-wide event feed, custom field creation and deletion, sending-provider configuration, seed sends, and the bulk reset_status action. These are read and performed by a signed-in operator.

Practical advice#

• Prefer one key per integration, not one shared key for every system.
• Use the smallest scope set that still lets the integration work.
• Reserve broadcasts:schedule for systems that truly need send authority.
• Rotate keys if a vendor changes, an environment is retired, or a secret may have leaked.