Permissions and least privilege
A key carries a set of scopes, chosen when it is created and fixed for its
lifetime. Every protected route checks for a specific scope, and a key
without it gets 403 Insufficient scope naming the scope it wanted.
The full list of twenty lives on the Authentication page. This page is about choosing among them.
Scopes come in read and write pairs
Almost every scope is thing:read or thing:write, and write does not imply
read. A key that creates templates and also lists them needs both
templates:write and templates:read.
Three do not follow the pattern:
| Scope | |
|---|---|
tenant:read |
Usage, health, storage and activity figures |
tenant:admin |
Team, billing and API keys. The most dangerous scope there is |
directory:sync, scim:provision |
Machine identities for an AD sync agent and an identity provider |
Least privilege in practice
The useful question is not “what might this ever need” but “what breaks today if I leave this out”.
| What it does | What it needs |
|---|---|
| Sends transactional mail | send:write |
| Sends, and checks delivery | send:write, send:read |
| Sends from stored templates | the above, plus templates:read |
| Honours unsubscribes it manages itself | plus suppressions:read, suppressions:write |
| Receives webhooks only | nothing. Webhooks are pushed to you; the scope is for managing subscriptions |
Most integrations are the first row. send:write alone is a genuinely common
and correct answer.
There is a real tension with keys being immutable:
narrowing is safer, but widening later costs a full rotation. The resolution is
to scope a key to the job the service does, not to the single endpoint it
calls this week. A sending service gets the sending scopes. It does not get
mailboxes:write because someone might add a feature.
Scopes are not the only gate
A scope can be necessary without being sufficient. Two other checks run:
Account mode. Mailbox endpoints need hosted mailboxes, so on a Lockally API
account they return 403 Business mode required whatever scopes the key
carries. Granting mailboxes:read cannot unlock them, because there are no
mailboxes to act on. The error carries "code": "business_mode_required" so
you can tell it from a scope failure.
Plan. API keys themselves are a plan feature, checked on every request, not just at creation.
Per-mailbox grants
inboxes:read and inboxes:write are not account-wide, and this catches
people out. Holding the scope lets a key use the inbox endpoints at all; it
does not say which mailboxes.
Each mailbox is granted to a key one at a time:
POST /v1/api-keys/{keyID}/mailboxes {"mailbox": "support@yourcompany.com"}
GET /v1/api-keys/{keyID}/mailboxes
DELETE /v1/api-keys/{keyID}/mailboxes/{mailboxID}
All three need tenant:admin.
A mailbox with no grant answers 404, not 403. That is deliberate: a key
should not be able to map which mailboxes exist by probing for a different
status. The detail does not pretend otherwise:
{
"status": 404,
"title": "Mailbox not found",
"detail": "No such mailbox, or your key has no grant for it. Grants are managed via POST /v1/api-keys/{id}/mailboxes."
}
So a missing grant and a mistyped address are indistinguishable by status. Check the grant list before assuming the address is wrong.
Grants apply to API keys only. An admin session reaches any mailbox on the account without them, which is why a key is the right credential for anything automated.
A grant is refused for a mailbox with agent access disabled, or one holding an active end-to-end encryption key. In the second case the server genuinely cannot read the mailbox, so a grant would be a promise it could not keep.
This is the strongest least-privilege tool here: a key for an assistant that
answers support@ can be granted that one mailbox and reach nothing else, even
though the scope is spelled the same as one that could reach many.
What a key can never carry
webmail is a real scope, and not grantable on an API key. It is minted by
the server for a single mailbox session and pins a request to that mailbox. A
tenant able to request it on a console key would hold something that looks
mailbox-owner-scoped to every check that matters, which is the opposite of what
those checks are for.
Asking for it, or for any scope that is not one of the twenty, fails key creation with the full valid list in the error.