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 on the next request. Anything already queued still goes out — revoking a key stops new requests, it does not recall sent mail.

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
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.