API Authentication

Every request to the Sent API v3 carries exactly one credential: an API key in the x-api-key header. There is no OAuth handshake, no token refresh, and no session. This page explains why authentication works this way, what the design trades away, and what it asks of you in return.

One key, resolved on every request

When a request arrives, the API looks up the presented key, resolves it to your customer account, and attaches that identity to the request. Nothing persists between calls: each request is authenticated independently, and the server keeps no session on your behalf. That is why the API has no login step: the key is the entire credential on every call.

This model has a name in HTTP security: the key is a bearer credential. Whoever presents it is treated as the account. Most of the security guidance around Sent API keys follows from that single property.

Why a header, not a URL or body

A credential can travel in three places in an HTTP request: the query string, the body, or a header. Query strings are the worst home for a secret, because they are routinely written to server access logs, proxy logs, and browser history, so a credential in a URL leaks by default. The request body is safer, but it ties authentication to methods that have bodies, leaving GET requests with nowhere to put the credential. A header is the remaining channel: it is uniform across HTTP methods and conventionally excluded from logs. The same reasoning leads most API-key platforms to the same design.

A header is plaintext inside the connection, so its confidentiality rests entirely on TLS. This is why the API is served over HTTPS, and why a key should never travel over an unencrypted channel.

Why not OAuth

OAuth exists to solve delegation: a third-party app acting on a user's behalf without ever seeing the user's password. Calls to the Sent API are not delegated (your backend acts on your own account), so an OAuth flow would add token issuance, expiry, and refresh without adding a security boundary.

Some platforms use OAuth client-credentials even for first-party, server-to-server APIs, because short-lived tokens bound how long a leaked credential remains useful. That is a reasonable approach, but it means every integration must implement token acquisition and refresh before it can make its first call. Sent chooses the other side of that trade: a static key makes the first request a one-liner, and containment comes from revocation and rotation. You can disable or delete any key in the dashboard, and it stops working immediately.

What the trade-off asks of you

Because the key is a static bearer credential, the burden the design places on you is key handling. Each of the standard practices exists for a specific reason:

• Environment variables instead of source code, because repository history is effectively permanent: a key committed once remains recoverable even after you delete it.
• Server-side use only, because anything delivered to a browser or bundled into a mobile app is public; a key there is equivalent to publishing it.
• One key per environment, because separate keys contain the blast radius of a leak and let you rotate development credentials without touching production.
• Periodic rotation, because rotation bounds the useful lifetime of a key that leaked without your knowledge.

All four practices answer the same underlying fact: possession of the key is authorization.

The how-to guide Creating and managing API keys turns them into concrete steps.

Guarding against brute force

A single static credential invites guessing, so the API tracks consecutive failed attempts per presented credential and temporarily locks a credential after repeated failures, with lockout periods that escalate from 1 minute up to 60 minutes.

The lockout is keyed to the credential itself rather than to the caller's IP address. This is deliberate: many tenants can sit behind one shared ingress or proxy and therefore share an IP, so an IP-keyed lockout would let one misconfigured client (or a scanner probing random keys) lock out every valid tenant behind the same address. Scoping the lockout to the guessed credential means a valid key is never collateral damage.

Where to act on this

• Creating and managing API keys: create, store, verify, and rotate keys.
• Authentication reference: the exact header, response headers, and AUTH error codes.
• Per-request authentication pattern: the integration blueprint for multi-tenant apps where each customer supplies their own key.