Authentication

Every request carries a project API key as a bearer token.

Authorization: Bearer ss_live_...

ss_live_… keys send real email from verified domains.
ss_test_… keys simulate everything and never deliver.

A key belongs to one project

You never pass an organization or project id. A key can only touch its own project’s domains, templates, webhooks and messages, and a request that includes such an id is rejected.

Scopes

Scope	Allows
`emails:send`	Send email.
`emails:read`	Retrieve and list emails, read usage.
`domains:manage`	Add, check and remove domains.
`templates:manage`	Create and read templates.
`webhooks:manage`	Manage webhook endpoints and deliveries.
`suppressions:manage`	Add, list and remove suppressed addresses.
`api_keys:manage`	Create, change and revoke other keys. No key has it by default.
`contacts:manage`	Manage audiences, contacts, topics and contact properties. Not in a key unless you choose it.
`inbound:manage`	Read and delete received email.
`broadcasts:manage`	Create, send and cancel broadcasts. Not in a key unless you choose it.

Give each key only the scopes it needs. A server that only sends needs just emails:send.

Managing keys with a key

A key with api_keys:manage can create, list, update and revoke keys in its own project. It can only hand out permissions it has itself, and cannot touch a key more powerful than itself, so it can never be used to gain more access. Grant it only to automation you trust, such as a deployment tool that rotates keys.

Keeping keys safe

Keep keys on your server, in environment variables. Never put one in browser or mobile code.
Create a separate key per app or environment, so you can revoke one without touching the rest.
If a key leaks, revoke it in the dashboard. It stops working immediately.
Repeated failed attempts from one address are temporarily blocked.