DocsAuthentication

Authentication

Every request carries an API key as a bearer token. Keys are scoped — a leaked email:read key cannot mint new sends.

Bearer tokens

Set a single header on every server-to-server request.

Authorization: Bearer sdx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl https://sendix.dev/api/v1/domains \
  -H "Authorization: Bearer $SENDIX_API_KEY" \
  -H "Accept: application/json"

Read the key from a secret manager or environment variable. Do not put it in a query string: URLs are commonly stored in browser history, reverse-proxy logs, analytics, and monitoring tools.

Key restrictions

Scopes define actions. Restrictions further narrow where and for how long they work.

Domain scope

All or selected

A restricted key can send only from domain IDs selected when the key is created.

IP allowlist

Up to 32 entries

Requests outside the configured IP or CIDR ranges are rejected as unauthorized.

Expiration

Optional timestamp

Use expires_at for CI, migrations, vendors, and other short-lived credentials.

Restrictions are cumulative. A key with email:send still fails if its source IP is not allowed, it is expired, or the From domain is outside its domain scope.

Authentication failures

Status	Interpretation	Action
401	Missing, malformed, unknown, revoked, expired, or IP-restricted key.	Stop retrying; inspect secret selection and key restrictions.
403	The key is valid but lacks the route scope or domain permission.	Use an appropriately scoped key; do not loop retries.
429	The caller is authenticated but a request limit was reached.	Honor Retry-After and keep the same idempotency key.

Client-facing errors intentionally reveal little

Several invalid-key conditions share a 401 response so an attacker cannot use the API to enumerate key state. Use the dashboard key metadata and audit trail to distinguish expiration, revocation, and IP restriction during incident response.

Zero-downtime rotation

Rotate deliberately so old and new deployments can overlap.

1. Rotate the key in the dashboard and choose the overlap window.
2. Store the new plaintext immediately; it is shown only once.
3. Deploy the new key to every instance and verify successful requests.
4. Revoke the old key early, or let its rotation expiry end the overlap.

Rotation preserves the old key's scopes, domain selection, and IP allowlist on the new credential. The overlap can be from 0 to 72 hours and defaults to 24 hours.

Key shape

Prefix

sdx_live_

Live API keys are scoped and can be revoked instantly.

Length

41 characters

32 random + 9-character prefix.

Storage

Shown once

The plaintext is unrecoverable after the create call returns.

Scopes

Grant the minimum your integration needs. Read scopes are strictly weaker than the matching :manage scope.

Scope	Kind	What it lets the key do
email:send	write	Mint outbound mail and schedule broadcasts.
email:read	read	List, retrieve, and inspect delivery history.
domain:read	read	View domains and their DNS verification status.
domain:manage	write	Add, verify, or remove sending domains.
tenant:read	read	List managed customers and inspect their domains and provider state.
tenant:manage	write	Create, update, pause, and remove managed customers and their domains.
webhook:read	read	List webhooks and inspect delivery attempts.
webhook:manage	write	Create / update / delete webhook endpoints and secrets.
analytics:read	read	Read aggregate stats and time-series for the workspace.
logs:read	read	Read structured email logs (recipient + per-event timeline).
suppression:read	read	View suppression list entries and reasons.
suppression:manage	write	Add or remove entries from the suppression list.
template:read	read	List templates and read their active source.
template:manage	write	Create / edit / publish / archive templates.
audience:read	read	List audiences, contacts, and segments.
audience:manage	write	Mutate contacts, segments, and audience metadata.
automation:read	read	Inspect automation definitions and their run history.
automation:manage	write	Create / edit / archive automations.
automation:run	write	Trigger an automation run from an external system.
billing:read	read	Read invoices, usage, and plan details.
billing:manage	write	Change plan, update payment methods.
key:manage	danger	Reserved for dashboard key administration; API-key callers cannot manage API keys.

Safety

Treat keys like passwords

Never commit keys to version control, print them in application logs, paste them into tickets, or expose them in browser/mobile bundles. Rotate immediately on suspected exposure. Keep separate keys per environment and workload so one revocation has a small blast radius.