Handling API keys

Keep usend API keys safe in code, CI and production.

An API key sends email as your organization. Treat it like a password.

Use the right key for the job

Permission	Use it for
`sending_access`	Your application servers. It can only call `POST /emails` and `POST /emails/batch`.
`sending_access` limited to one domain	Anything tied to one brand or customer domain.
`full_access`	Admin tools and scripts that manage domains, contacts and webhooks. Keep these few.

Create one key per application and environment (staging, production). If one leaks, delete it without touching the others. See API keys.

Use environment variables or a secrets manager (Vercel/Cloudflare secrets, AWS Secrets Manager or SSM, Kubernetes secrets, Doppler, 1Password).
Never commit a key to Git, including in .env files. Add .env* to .gitignore and commit an .env.example without values.
Never put a key in client-side code, a mobile app, or a public bucket. See CORS.
Do not paste keys into chat, tickets or screenshots.
Keys are shown once at creation. usend stores only a hash, so a lost key cannot be recovered; create a new one.

The same key is the password for SMTP, so the same rules apply to your CMS, printers and plugins.

Create a new key.
Deploy it.
Check that the old key's last_used_at stops changing (the dashboard shows it; the GET /api-keys response has the field).
Delete the old key.

Do this on a schedule (for example every 90 days) and whenever someone with access leaves.

The Logs page shows every API request with the key's name, IP and user agent. Unfamiliar user agents or a surprise spike point at a leak.
Use sending_access keys limited to a domain so a leak cannot be used elsewhere.
Turn on secret scanning in your Git host. Keys start with us_, which makes them easy to detect.

If you suspect a leak, follow Handling leaked API keys.