Authentication
The API key
Every public API request authenticates with an API key in the Authorization header:
curl https://api.notideus.io/v1/emails \
-H "Authorization: Bearer nt_live_…"
A key secret is nt_live_ followed by 32 random characters. It is shown once, at creation. From then on the dashboard displays only the prefix — nt_live_ plus four characters, e.g. nt_live_A3f9 — and the server stores just the sha256 hash of the secret.
{
"error": {
"code": "unauthorized",
"message": "missing or invalid api key"
}
}
Scopes
Each key carries one or more scopes, and every route requires one:
| Scope | Grants |
|---|---|
full | Wildcard — everything below |
emails:send | POST /v1/emails, POST /v1/emails/batch |
whatsapp:send | POST /v1/whatsapp/messages, POST /v1/whatsapp/messages/batch |
contacts:read | GET contact routes |
contacts:write | POST, PATCH, DELETE contact routes |
full is a wildcard that grants every scope — handy for getting started, but prefer narrowly scoped keys per service in production.When the key lacks the route's required scope, the API returns 403 Forbidden:
{
"error": {
"code": "insufficient_scope",
"message": "api key lacks the emails:send scope"
}
}
Domain binding
At creation, a key may optionally be bound to one of your verified domains (domain_id). A bound key can only send from that domain: if the request's From address resolves to a different domain, the send fails with 403 domain_not_allowed. Use binding for send-only services that should never touch your other domains.
API keys are created and revoked from the dashboard — key management has no public API.
Security practices
- Store secrets in an environment variable or a secrets manager — never in client-side code, never in version control.
- Rotate by creating a new key, deploying it, then revoking the old one — revoking takes effect immediately.
- Give each service its own key with only the scopes it needs (
emails:sendfor senders,contacts:writefor sync jobs), so a leaked key is contained. - Bind keys that only send from one domain; a leaked bound key cannot be abused to send from your other domains.