Skip to Content
Docs

Authentication

API keys, permission scopes, and domain-scoped keys for the emitd API.

Every route in the emitd API except GET /health authenticates with an API key passed as a Bearer token:

Authorization: Bearer esk_live_...

Create keys in the console under API keys. A key is shown in full exactly once at creation — emitd only ever stores a SHA-256 hash of it, so a leaked database never exposes a usable key.

Permission levels

Every key carries one of two scopes (email_core::KeyPermission):

  • full_access — read, send, and manage every resource: contacts, audiences, segments, broadcasts, automations, templates, webhooks, suppressions, messages, inbound.
  • sending_access — send email only (POST /v1/email, POST /v1/email/batch). Every other route responds 403 insufficient_scope.

Domain-scoped keys

A sending_access key may additionally be scoped to a single verified sending domain. Sends from any other domain fail with from_domain_not_verified. Domain-scoped keys are the right shape for a single service that should never be able to send as another brand:

Authorization: Bearer esk_live_...   # scoped to mail.acme.com only

Feature-limited keys

A full_access key can be limited to features — email, messages, templates, contacts, audiences, segments, suppressions, webhooks, inbound, broadcasts, automations, domains, analytics. A request to a route outside the key's features responds 403:

{ "error": "feature_not_enabled", "feature": "contacts" }

Choose features when you create a key, or change them later, in Console → API keys. Keys created without a feature list have every feature. Limited keys are the right shape for AI agents: an agent connected through MCP sees only the tools for its key's features.

IP-limited keys

A key can be limited to the addresses your servers send from. A stolen key is then useless anywhere else. Add addresses or ranges like 203.0.113.0/24 when you create a key, or later, in Console → API keys. A request from any other address responds 403, on every route, and names the address so you can add it:

{
  "error": "ip_not_allowed",
  "ip": "203.0.113.9",
  "detail": "This API key can't be used from 203.0.113.9. A workspace admin can add this address in Console → API keys."
}

Keys created without a list work from anywhere. List every server that uses the key, because a change takes effect on the next request. Serverless platforms have no fixed outbound address, so leave the list blank there unless yours gives you one. Keys used through MCP are checked against the address of the MCP client.

Guardrails

Any key can also carry guardrails: allowed senders, allowed recipient domains, a recipient limit per email, a daily cap, and when a person must confirm a send. A send the guardrails refuse responds 403 policy_violation; one that needs a person responds 202 with status: pending_approval and waits in Console → Approvals. See Guardrails and approvals.

Good practice

  • Keep keys in environment variables or a secrets manager, never in source control.
  • Use a separate key per service, so you can revoke one without downtime.
  • Revoking a key takes effect immediately — the next request with it gets 401 unauthorized.
  • Prefer sending_access for anything that only delivers mail.

A missing, malformed, or unknown key returns 401:

{ "error": "unauthorized" }

Never ship a key in client-side code

API keys are server-side credentials. A key in a browser bundle is a key in the wild — call emitd from your backend or a serverless function.

On this page