Authentication and API keys

Each key belongs to one integration and one workspace. Send its secret with every request:

Authorization: Bearer YOUR_API_KEY

The route identifier must match the key’s workspace. Use an integration credential for integration requests.

Choose permissions by operation

Profiles: contacts:read, contacts:write and contacts:delete.
Subscription: contacts:email:subscribe. Recording or importing evidence also requires the explicit contacts:email:consent:import permission.
Audiences: segments:read and segments:write. The latter also creates and saves custom field definitions; reading them uses contacts:read.
Sending: emails:send:transactional or emails:send:marketing, depending on purpose.
Email lookup and analytics: emails:read. Reading an email’s events also requires events:read.
External automation events: events:write.

Both key and integration must remain active and allow the operation. Authorization is checked again when pending work runs; a revoked key does not retain access because it started an earlier operation.

Rotate credentials

Create a new key, update your backend secret, verify an allowed operation and revoke the previous key. The secret appears only at creation and cannot be retrieved from the list. An idempotent replay of creation does not reveal it again.

Idempotency belongs to the integration, so rotating its keys does not create a different operation identity. Keep the same idempotency key when retrying the same operation with a new credential from that integration.

Understand access boundaries

Keys have no administrative access to billing, members, senders, designs, broadcasts, automations or webhooks. Those routes require a human session. A route unavailable to integrations returns 404; adding permissions does not enable it.

See Integrations and API keys and errors.