> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotascale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grants

> A grant is a bounded authority a named human signed for. It is the object everything else on this site refers back to.

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

| Field                 | What it does                                                              |
| --------------------- | ------------------------------------------------------------------------- |
| `agent_id`            | The one agent this authority is for. Grants are not shared.               |
| `principal_type`      | `human`, `team` or `service`. Whose behalf the agent acts on.             |
| `principal_id`        | The accountable party. For `human`, a real person.                        |
| `scope`               | A map of what may be done, for example `{"tool": ["payments.transfer"]}`. |
| `budget_amount_minor` | A spend ceiling, in minor units.                                          |
| `budget_currency`     | Three-letter code.                                                        |
| `budget_count`        | A call ceiling, separate from spend.                                      |
| `ttl_hours`           | How long it lives. Defaults to 24.                                        |
| `conditions`          | Extra requirements, such as needing a clean context.                      |
| `policy`              | A policy expression evaluated at gate 7.                                  |
| `delegation_policy`   | `none` or `attenuating`. See [Delegation](/concepts/delegation).          |
| `audience`            | Who the resulting credential is for, when the grant mints one.            |

## 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.

<Note>
  Amounts are in **minor units** and integers throughout. There is no float
  anywhere in the money path. 25,000.00 EUR is `2500000`.
</Note>

## 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.

```http theme={"system"}
POST /v1/grant-families
POST /v1/grant-families/{family_id}/instantiate
```

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

<CardGroup cols={2}>
  <Card title="Issue a grant" icon="file-signature" href="/guides/issue-a-grant">
    The call, with a real payload.
  </Card>

  <Card title="Delegation" icon="sitemap" href="/concepts/delegation">
    What happens when an agent hands work to another agent.
  </Card>
</CardGroup>