API keys
A key for each job, and nothing more.
Give each service its own key, holding only the scopes and senders it needs. Every call it makes is on the record.
In short
What is an API key?
A secret your code sends with each request. It says which workspace the call is for and what it is allowed to do.
32
scopes to choose from
25
whole domains in one send scope
3,650
days, the longest expiry
How it works
A role as a ceiling
Attach a role and the key can never do more than it allows. GET /ping shows what the key names and what the role left it.
Limit who it sends as
Up to 25 whole domains and 50 single addresses. A sender outside them gets a 403.
Every call on the record
Method, path, status, error and duration for each request, with the busiest routes and how often they fail.
Check what a key can do
GET /ping needs no scope and answers with the key's reach.
{ "ok": true, "keyId": "4c1b257a66287fd113bd89d0", "mode": "live", "scopes": ["emails:send", "templates:write", "members:write"], "roleId": "role_2b81de079c1f0a4b7e05d386", "grantedScopes": ["emails:send", "templates:write"], "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}What you get
In the product today
Rotate in place
A new secret, with the same id, scopes and history.
Revoked, not deleted
A later call is told revoked_api_key.
Expiry built in
Set a key to lapse, up to ten years out.
Good practice
Getting the most out of it
- 01
One key per service
A leak then costs one integration, not all of them.
- 02
Grant the least
Start from emails:send and add scopes when a call needs them.
- 03
Watch the failures
Filter the request log to failed calls after a deploy.
Where it stands
Good to know
- No IP allowlist
- A key cannot yet be tied to the addresses of your servers.
- No test keys
- Only oe_live_ keys can be created, so every send is real.
- No log over the API
- The request log is read in the app, not through a REST route.
Questions
Asked often
Keep going
Works well with
Start
Your domain,
your mail.
Point a domain at OpenEmail and read it in a mailbox built around it. The free plan covers one domain.
