Scoped grant
A scoped grant is a credential limited to named projects, inboxes and permission scopes, whose effective authority is recomputed from current database state on every request instead of being trusted as a fixed claim set.
Most systems treat a credential as a claim set: the token says what the holder may do, and the server believes it until the token expires. A scoped grant inverts that. The token is a lookup handle, and what the holder may do is worked out again, from scratch, on every request.
What the grant is scoped to
Four things, all of them named at creation.
A project, which also fixes the environment. An efa_test_ key resolves only to
test projects and test inboxes; an efa_live_ key only to live ones. No flag crosses
the boundary, because the boundary is in the key prefix.
A set of inbox IDs. A grant that names one mailbox cannot read another in the same project, which is what stops a single-purpose assistant from having a view of the whole workspace.
A set of permission scopes, drawn from 32 strings. They are fine-grained enough
that reading and sending are separate (messages:read, messages:send), drafting
and submitting a draft are separate (drafts:write, drafts:submit), and reading an
approval is separate from deciding one (approvals:read, approvals:decide). The
useful consequence is that a credential can be given the power to compose a fully
formed reply and no power at all to transmit it.
A human, recorded as the authorising identity. This is the part that does the most work, and it is covered below.
The three enforcement rules
A credential cannot exceed its creator. Requesting a scope your own role lacks
fails at creation with permission_denied. Not later, at use time, when the failure
would be a production incident instead of a setup error.
Environment is carried in the key prefix and cannot be crossed. There is no parameter that lets a test credential reach a live inbox, so a development run cannot contact a real customer by misconfiguration.
Authority is re-read on every request. The effective permission set is recomputed from current database state each time and intersected with the current grant of the human who authorised it. Remove that person’s project assignment and every credential they minted narrows on the next request, with no revocation step and no window in which a cached token still works. Scoped credentials for agent email works through what that means for key rotation.
Two shapes, one model
A scoped grant appears in two forms. A REST key is a secret you store, created
against a project with an explicit scope list and inbox list, returned once in
secret and never shown again. A connection grant is an OAuth authorisation a human
approves in a browser, which resolves to one of three presets and expires after 30
days.
They are not different permission models. Both resolve to the same scope strings and both are subject to the three rules above. The difference is who chooses the scope and who holds the secret, which is a deployment question rather than a security one.
What a scoped grant does not do
It does not decide whether a send transmits. Scope decides what the agent may attempt;
inbox policy decides what actually leaves. A credential with messages:send still
gets approval_required on an inbox set to hold everything, and a credential without
it is held even on an inbox that permits direct sending. The two controls compose, and
approvals and permissions is where that composition is laid out.
It does not expire on its own. A REST key has no default lifetime, so an unrotated key is a standing grant until somebody revokes it. Set an expiry when you create one.
And it is not an audit log. A grant records what an agent may do. What it did is a
separate record, and by design the administrative scopes that would let an agent
tamper with that record, including keys:manage, messages:delete and
exports:write, cannot be attached to an agent-facing connection at all.