---
title: grants operations
---

The exact fields each `grants.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/ja/reference/http-api#request) its namespace and agent; see [identities and namespaces](/ja/concepts/identities-and-namespaces). The [operations index](/ja/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `grants.approve`

Approve (or reject) a pending grant request.

`POST /v1/grants.approve` · MCP `loom_grants_approve` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `subject` | `str` | required | Whose pending request to decide: an email or a service-account `sub` claim. |
| `decision` | `Literal['approve', 'reject']` | `'approve'` | `approve` makes the requested (or overriding) role active; `reject` drops the request, keeping any base role, or removes the row when the subject had no base access. |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | `None` | Approve with a different role than was asked for (a maintainer request answered as reader). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `subject` | `str` | The subject as the request spelled it. |
| `namespace` | `str` | The namespace the op reads or writes. |
| `decision` | `Literal['approve', 'reject']` | The decision applied (echoes the request). |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | The role approved (for `reject`, the role the request would have had); None when no grant row existed for the subject. |
| `decided_at` | `datetime` | When the decision was written (UTC). |

## `grants.create`

Grant another subject (user or service-account) viewer / writer / admin role on a namespace.

`POST /v1/grants.create` · MCP `loom_grants_create` · role `admin` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `subject` | `str` | required | A login handle, an email (it admits an account once that email is verified: an SSO account's or a linked one's), or a service-account `sub` claim. |
| `role` | `Literal['viewer', 'writer', 'admin']` | required | `viewer`, `writer` or `admin`; a code namespace takes only `viewer` (reader) and `admin` (maintainer). |
| `granted_by` | `str` | `'admin'` | Ignored under auth: the server stamps the authenticated caller. |
| `replace` | `bool` | `False` | The table replaces on (org, namespace, subject), so a create below the subject's current active role would lower it silently. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `subject` | `str` | The subject as the request spelled it (the row is stored under the login handle of the account whose verified email it is, else as spelled). |
| `role` | `Literal['viewer', 'writer', 'admin']` | The role now active for the subject. |
| `granted_at` | `datetime` | When the grant row was written (UTC). |

## `grants.list`

List active grants on a namespace — who has access, at which role.

`POST /v1/grants.list` · MCP `loom_grants_list` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `limit` | `int` | `100` | Rows per page, one per person, newest grant first; 1 to 500. |
| `cursor` | `str \| None` | `None` | Resume the previous page on the same namespace; unset for the first page. |
| `fields` | `list[str] \| None` | `None` | The output fields the caller reads (a whitelist resolved against the row model; an unknown name is a 422); unset, every field. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_GrantEntry]` | Live grants on the namespace, active and pending (revoked ones excluded), newest first; one row per person, their other spellings in `also`. |
| `next_cursor` | `str \| None` | Pass as `cursor` for the next page; None when this page is the last. |
| `truncated` | `bool` | True when more people follow this page (`next_cursor` is set). |

## `grants.pending_for_me`

Every pending request in the namespaces the caller administers, in one statement.

`POST /v1/grants.pending_for_me` · MCP `loom_grants_pending_for_me` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `limit` | `int` | `500` | At most this many requests, newest first; 1 to 2,000. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_PendingForMeEntry]` | Pending join or elevation requests in namespaces the caller administers, newest first; empty for an anonymous caller. |

## `grants.revoke`

Remove a subject's grant on a namespace.

`POST /v1/grants.revoke` · MCP `loom_grants_revoke` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `subject` | `str` | required | Whose grant to revoke: a login handle, an email or a service-account `sub`; the person's row under each verified spelling goes, and a pending request is rejected. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `revoked` | `bool` | True when any of the subject's grant rows was found and revoked; false when it had none. |
| `revoked_at` | `datetime \| None` | When the revoke was written (UTC); None when nothing was revoked. |

## `grants.share_agent`

Let another agent of the caller's trust read, or write, the caller's own namespace.

`POST /v1/grants.share_agent` · MCP `loom_grants_share_agent` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The calling agent's own namespace, the only one it may share. |
| `grantee` | `str` | required | The agent of the same trust to share it with, as its control plane names it. |
| `role` | `Literal['viewer', 'writer']` | `'viewer'` | What that agent may do there: `viewer` reads, `writer` also writes. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `namespace` | `str` | The namespace the op reads or writes. |
| `subject` | `str` | The subject the grant is stored under, `sa:<trust>:<agent>`. |
| `role` | `Literal['viewer', 'writer']` | The role now active for that agent. |
| `granted_at` | `datetime` | When the grant row was written (UTC). |

## `grants.unshare_agent`

Take back what the caller lent another agent of its trust.

`POST /v1/grants.unshare_agent` · MCP `loom_grants_unshare_agent` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The calling agent's own namespace. |
| `grantee` | `str` | required | The agent of the same trust whose grant there to revoke. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `revoked` | `bool` | True when the agent held a grant and it was revoked. |
| `revoked_at` | `datetime \| None` | When the revoke was written (UTC); None when nothing was revoked. |

<!-- prettier-ignore-end -->
