Authentication

SonarSend’s external API uses service-account API keys.

Key format#

A key looks like this:

sonar_7f3a9c2e1b8d4a6f5e0c3b7a9d2f4e6c1a8b5d3f7e9c2a4b6d8f0e3c5a7b9d1f
Copy

sonar_ followed by 64 lowercase hex characters (256 bits of randomness). The sonar_ prefix is there so a leaked key is recognizable — to you, to us in a support ticket, and to automated secret scanners.

Notes:

• There is no environment segment. Keys are not tagged live / test; a key belongs to one workspace and that is the only axis.
• The full key is shown exactly once, at creation. Store it in your secret manager immediately — it cannot be retrieved afterwards, only rotated.
• The key list shows a masked fragment (sonar_a1••••) so you can tell keys apart without exposing them.
• Keys issued before this format existed are 64 hex characters with no prefix. They remain valid — nothing needs to change. Rotating one issues a sonar_-prefixed replacement.

Base URL#

All requests are tenant-scoped:

https://YOUR-APP/t/YOUR-TENANT-SLUG/api/...
Copy

Example:

https://app.example.com/t/acme/api/broadcasts
Copy

Header#

Send your API key in the X-API-Key header:

X-API-Key: sonar_xxxxx
Copy

Example#

curl -X GET \
  "https://app.example.com/t/acme/api/email-types" \
  -H "X-API-Key: sonar_xxxxx"
Copy

Scopes#

API keys are scoped: a key can reach only the capability areas it was granted. This is the complete list.

Broadcasts

• broadcasts:read — view broadcasts and delivery stats
• broadcasts:write — create and edit broadcasts
• broadcasts:schedule — send and schedule delivery

Contacts

• contacts:read — view contact profiles and fields
• contacts:write — create, update, and delete contacts

Lists

• lists:read — view lists and memberships
• lists:write — create, update, and manage list membership

Segments

• segments:read — view segment definitions and counts
• segments:write — create and edit segments

Sequences

• sequences:read — view sequences and enrollments
• sequences:write — enroll contacts into sequences

Reports

• reports:read — view broadcast reports

Events

• events:write — push custom events via the API

Suppression

• suppression:read — view suppression lists
• suppression:write — add and remove suppressions

Custom fields

• custom-fields:read — view field definitions

Sending identities

• sending-identities:read — view sender addresses and domains

Templates & blocks

• templates:read — view templates and content blocks
• templates:write — create and edit templates and blocks

Full access

• * — every scope above. Prefer a narrow set; * exists for convenience, not as a recommendation.

Important behavior#

• write implies read within the same domain — a key with contacts:write can GET /api/contacts without also holding contacts:read.
• broadcasts:schedule is NOT implied by broadcasts:write. Creating and editing a broadcast is a separate grant from actually sending it, so a key that builds drafts cannot send them unless you say so.
• API keys cannot access session-only admin/account endpoints.
• A valid API key does not behave like a browser session.

Common auth errors#

Missing key#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
Copy

Valid key, wrong route#

{
  "error": {
    "code": "API_KEY_FORBIDDEN",
    "message": "Service account keys cannot access this route"
  }
}
Copy

Valid key, missing scope#

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This key is missing a required scope: broadcasts:schedule"
  }
}
Copy