Authentication

Bearer keys, scopes, and what to do if one leaks.

Every request to the API carries your API key as a bearer token. There is no other authentication method — no signed query strings, no cookies, no username and password.

Authorization: Bearer hme_yourkeyid_yoursecret

Send it over HTTPS only. The API does not accept plain HTTP.

The shape of a key

hme_yourkeyid_yoursecret
 │      │          └─ the secret half — shown once, never stored in readable form
 │      └─ the key id — safe to log, use it to identify or revoke the key
 └─ a fixed prefix so a leaked key is recognisable on sight

The key id is the part you can safely put in your own logs and support tickets. Never log or paste the whole key.

Scopes

A key carries only the permissions you give it. Grant the least it needs.

Scope	Lets the key	Needed for
`send`	send email	`POST /v1/send`, `POST /v1/send/batch`, scheduled sends, the email log
`domains`	add and verify sending domains	`POST /v1/domains`, `GET /v1/domains/:domain`, recheck
`templates`	manage saved templates	all `/v1/templates` routes

Scopes are deliberately separate. A key that can send cannot quietly add a new sending domain, and a key that manages domains cannot send. If a key leaks, the damage is bounded by its scope.

Rotating a key

A key cannot be un-issued by its value. To rotate:

Create the new key and deploy it.
Confirm your traffic is running on the new key.
Revoke the old key by its key id.

Revocation takes effect at once: on the next request, and on any email that key queued which has not left yet — it is not sent, and your email log shows it as failed with api_key_revoked. Mail that has already been sent cannot be recalled. So when rotating, wait a minute after your traffic moves to the new key before revoking the old one.

Expiry and last use

A key can be made with an expiry — 30, 90 or 365 days — or with none. When it expires it stops working exactly like a revoked key (api_key_expired), so make its replacement before then. Keys made without an expiry never expire.

Each key also shows when it was last used, refreshed about once an hour. A key that has not been used for months is one to revoke: it is a door nobody is watching.

If a key leaks

Revoke it immediately, then create a replacement. Because scopes are separate, check what that particular key could do: a send key could have sent mail from your verified domains, and that mail is in your email log.

Errors

Status	`error`	Meaning
401	`missing_api_key`	no bearer token on the request
401	`invalid_api_key`	key not recognised, or wrong secret
401	`api_key_revoked`	the key has been revoked
401	`api_key_expired`	the key has passed the expiry it was made with
403	`insufficient_scope`	the key lacks the scope this route needs

A 401 never tells you which half of the key was wrong. That is deliberate — it stops an attacker using the error message to confirm a valid key id.