Authentication

Every request to https://api.sendops.dev carries a Bearer token. There are two kinds, and they are interchangeable at the API — the difference is how you obtain the credential, not how you send it:

• an API key (sk_live_… / sk_test_…), issued from the dashboard — this page;
• an OAuth 2.1 access token, obtained from https://auth.sendops.dev — see OAuth 2.1.

Use a key to automate your own organization; use OAuth to act on behalf of your customers’ organizations, or when you want short-lived credentials. Keys are the simpler choice and are not deprecated.

The Send API on https://ingest.sendops.dev (early access) uses the same header and the same keys, but takes API keys only: an OAuth access token is refused there with 401 invalid_key.

The rest of this page is about API keys. Keys are scoped to one organization and granted a fixed set of permissions chosen at creation time.

The Bearer header

Authorization: Bearer sk_live_KQX...ZJ7

Both credential types travel in this one header — there are no session cookies, no signed-URL flow, no HMAC. If the header is missing, malformed, or the credential has been revoked, the response is 401 Unauthorized (or 403 when the credential is valid but is missing the required scope).

Key format

Keys are 32 random bytes (Base32-encoded, no padding) prefixed with their environment:

The first 8 characters after the prefix are stored in plaintext on our side so the dashboard and audit log can identify the key without exposing the secret. The secret itself is hashed (SHA-256) before storage — once you create a key, we can never show it to you again. If you lose it, you must rotate it.

Live vs. test keys

Both environments share the same data plane and scope vocabulary — there is no separate test sandbox. The difference is rate:

• Live keys run at the org’s configured per-minute rate limit — which is unset (unthrottled) by default.
• Test keys run at 10% of that ceiling — max(1, limit ÷ 10) — once a limit is configured.

See Rate Limiting for the full model. Most v1 endpoints are reads; a few write surfaces exist — contact roster writes, attribute management, and broadcast create/send (gated by their own *.manage scopes), plus append-only activity ingestion (api.activities.write). Use test keys for CI smoke checks and unit tests so noisy automation doesn’t burn your live budget.

Scopes

Scopes are SendOps ACL permission keys. The full catalogue is published unauthenticated as scopes_supported in the authorization server’s metadata, generated from the same catalogue the API enforces:

curl -s https://auth.sendops.dev/.well-known/oauth-authorization-server \
| jq -r '.scopes_supported[]'

To see what a particular credential carries, call /v1/_scopes with it — that endpoint is authenticated and reports the caller’s own scopes, which is how you confirm a scope edit has propagated past the 5-minute cache:

curl https://api.sendops.dev/v1/_scopes \
-H "Authorization: Bearer sk_live_..."

Scope keys are namespaced under api.* so they cannot be confused with the dashboard’s internal ACL permissions. Every scope you can attach to a key starts with api..

A request that hits an endpoint your key does not cover is rejected with 403 Forbidden and an RFC 7807 problem document. See Errors.

Creating, rotating, and revoking keys

All lifecycle actions happen in the dashboard, in Workspace → API Keys.

Create

Click Create API Key, give it a name, choose Live or Test, and select scopes. The raw secret is displayed once — copy it now. If you lose it before storing it, immediately revoke this key and create a new one. There is no recovery path.

If your org has enforce 2FA turned on, creating a key requires a fresh MFA challenge.

Edit scopes

You can update the scope set on an existing key without rotating it. The change is applied immediately and recorded in the audit log (api_key.scopes_updated).

Rotate

Rotation issues a new secret while keeping the same name and scope set. Both the old key and the new key continue to work for 24 hours — a hard, non-negotiable grace window. After 24 hours the old key is automatically revoked by a background job.

Use rotation when:

• You suspect a key may have leaked but want zero-downtime cutover.
• You’re rolling keys on a routine schedule.

Rotation does not require MFA — it’s the safe path because the old key still works while you deploy the new one.

Revoke

Revocation is immediate. Once revoked, the key is dead — every subsequent request returns 401. Use this when:

• You know a key has leaked.
• You want to retire a key that is no longer in use.

If your org has enforce 2FA turned on, revocation requires a fresh MFA challenge.

Revoking a key also revokes every key it obtained through an API key request, and lapses its open requests.

Keys minted from a request

A key issued through an API key request differs from one created in the dashboard in four ways: it always expires (the lifetime an admin approved, at most 90 days), it cannot be rotated or cloned, it can never hold api.api_keys.request, and it is revoked automatically when the API key or OAuth connection that asked for it is revoked. Rotating the requesting key moves its minted keys to the new key. In the key list a minted key shows Requested by and the credential that asked.

Lifecycle in the audit log

Every key lifecycle event appears in the org audit log:

• api_key.created — actor: the user who created it
• api_key.scopes_updated — actor: the user who edited; includes added/removed scope diff
• api_key.rotated — actor: the user who rotated; emitted on both the old and new key
• api_key.revoked — actor: the user who revoked it (manual)
• api_key.grace_expired — actor: system; emitted when the 24h rotation grace ends

Request-level activity (which key called which endpoint when) is not in the audit log, and the dashboard does not show it per request. What it does show is each key’s Last used time, on Workspace → API Keys.

Storing keys safely

A few practical rules:

• Put the key in your secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler — anything but a .env file in version control).
• Inject the secret into your runtime via environment variable, never hard-code it.
• Add the key prefix (sk_live_ or sk_test_) to your repository’s secret-scanning denylist.
• Rotate on a cadence appropriate to your blast radius (we recommend at least annually for long-lived service keys, and immediately whenever a teammate with access leaves).