Skip to main content
A grant says what one agent may do, on whose behalf, up to what value, until when, and under what conditions. It is data, it has an identity, and it names a person. That last part is the whole point. A service account is not attribution, it is the absence of attribution written down. When an auditor walks up the chain from an action, a grant is where the walk ends: at somebody who signed.

​
What a grant carries

​
Two ceilings, not one

budget_amount_minor and budget_count are separate limits and both are enforced. An agent can be inside its spend ceiling and out of calls, which returns exhausted rather than deny, because retrying cannot help.
Amounts are in minor units and integers throughout. There is no float anywhere in the money path. 25,000.00 EUR is 2500000.

​
Grants expire on purpose

ttl_hours defaults to 24 and the default is doing work. An authority with no expiry is an authority nobody revisits, and the most common finding in an agent estate is a mandate granted for a migration in March that is still live in November. If you want something long-lived, say so explicitly and put a number on it. The grant is the artefact that records you did.

​
Grant families

A grant family is a template. Rather than issuing the same shape of authority by hand fifty times, you define it once and instantiate it per agent or per task. The family is the thing that gets reviewed; the instances inherit its bounds.
This matters at scale for a reason that is not convenience: when somebody asks what your payment agents are allowed to do, the answer is one family rather than fifty grants that have quietly drifted apart.

​
Approval

A grant can require approval before it becomes active. Those sit in GET /v1/grants/pending until somebody calls POST /v1/grants/{grant_id}/approve. The approving identity is recorded, and it is the identity the chain terminates at.

​
Next

Issue a grant

The call, with a real payload.

Delegation

What happens when an agent hands work to another agent.