Authentication

Sonar API uses bearer tokens. Generate a key per integration with the minimum scope required - keys are workspace-scoped and never cross orgs.

Generating a key

Go to Settings / API keys and click Create API key. Pick a descriptive name and only the scopes you need. The plaintext key is shown once - copy it immediately. If you lose it, revoke and re-issue.

Store keys like passwords. Never commit to source control. Rotate quarterly and on suspicion of leak.

Sending requests

Pass the key in the Authorization header:

bash
curl -H "Authorization: Bearer sk_<your-key>" \
  https://sonar-cyan-seven.vercel.app/api/v1/leads

Scopes

Scope	Grants
`leads:read`	List leads and read individual leads (incl. attached calls).
`leads:write`	Create, update, soft-delete leads. Does not grant read.
`runs:read`	Read agent run state and step outputs.
`runs:write`	Start agent runs. The runner uses the workspace's admin context for attribution.
`webhooks:read`	Inspect webhook subscriptions and delivery history.

Errors

401 Unauthorized

Missing, malformed, revoked, or unknown bearer token.

403 Forbidden

Valid key but missing the required scope for this endpoint.

Audit trail

Every API key use is timestamped (last_used_at visible in the settings UI). Mutating calls (POST / PATCH / DELETE) write an audit-log entry with source: apiand the calling key's id.