---
title: "`grants` 操作"
---

<!-- i18n: source=docs/reference/operations/grants.md blob=2f19ca501aab2dc4bc26f5ffd268d4f65aa8e98f model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/grants.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/grants.md), which is authoritative.

<a id="grants-operations"></a>

每个 `grants.*` 操作接受和返回的确切字段。

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

每个操作在 HTTP 上都是 `POST /v1/<op>`，在 MCP 上对应工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）会在传输层能够提供时，从令牌和 MCP 会话中填充；对于在单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们保留各自平面的 org）之外，所有操作的 org 都取该安装的 org，并且在[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)上，其命名空间和 agent 也由安装填充；参见[身份与命名空间](/docs/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并列在 `ignored_args` 中。

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

<a id="grantsapprove"></a>

## `grants.approve`

批准（或拒绝）一个待处理的授权请求。

`POST /v1/grants.approve` · MCP `loom_grants_approve` · 角色 `admin` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `subject` | `str` | 必填 | 要处理其待处理请求的主体：电子邮件或服务账号的 `sub` 声明。 |
| `decision` | `Literal['approve', 'reject']` | `'approve'` | `approve` 使所请求的角色（或覆盖指定的角色）生效；`reject` 丢弃该请求并保留其原有的基础角色，若该主体没有基础访问权限，则删除对应的行。 |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | `None` | 以不同于请求的角色批准（例如维护者请求被作为读者批准）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `subject` | `str` | 请求中所写的主体。 |
| `namespace` | `str` | 该操作读取或写入的命名空间。 |
| `decision` | `Literal['approve', 'reject']` | 已应用的决定（与请求一致）。 |
| `role` | `Literal['viewer', 'writer', 'admin'] \| None` | 被批准的角色（对于 `reject`，为该请求原本会获得的角色）；若该主体不存在授权行，则为 None。 |
| `decided_at` | `datetime` | 决定的写入时间（UTC）。 |

<a id="grantscreate"></a>

## `grants.create`

授予另一个主体（用户或服务账号）对某个命名空间的 viewer / writer / admin 角色。

`POST /v1/grants.create` · MCP `loom_grants_create` · 角色 `admin` · 幂等 · 已审计

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `subject` | `str` | 必填 | 登录名、电子邮件地址（一旦该邮箱通过验证，即可对应到某个账号：SSO 账号的邮箱或已关联账号的邮箱），或服务账号的 `sub` 声明。 |
| `role` | `Literal['viewer', 'writer', 'admin']` | 必填 | `viewer`、`writer` 或 `admin`；代码命名空间只接受 `viewer`（读者）和 `admin`（维护者）。 |
| `granted_by` | `str` | `'admin'` | 启用认证时会被忽略：服务器会写入已认证的调用方。 |
| `replace` | `bool` | `False` | 该表按 (org, namespace, subject) 进行替换，因此如果创建的角色低于该主体当前生效的角色，会在无提示的情况下将其降级。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `org` | `str` | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 该操作读取或写入的命名空间。 |
| `subject` | `str` | 请求中所写的主体（该行会存放在已验证该邮箱的账号的登录名之下，否则按请求中的写法存放）。 |
| `role` | `Literal['viewer', 'writer', 'admin']` | 该主体当前生效的角色。 |
| `granted_at` | `datetime` | 授权记录的写入时间（UTC）。 |

<a id="grantslist"></a>

## `grants.list`

列出命名空间上的有效授权：谁拥有访问权限，以及对应的角色。

`POST /v1/grants.list` · MCP `loom_grants_list` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `limit` | `int` | `100` | 每页的行数，每人一行，最新授权在前；范围为 1 到 500。 |
| `cursor` | `str \| None` | `None` | 在同一命名空间上继续上一页；首页不设置。 |
| `fields` | `list[str] \| None` | `None` | 调用方要读取的输出字段（白名单，按行模型解析；未知名称会返回 422）；不设置时返回全部字段。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_GrantEntry]` | 命名空间上的有效授权，包括已生效和待生效的（不含已撤销的），最新在前；每人一行，其其他写法放在 `also` 中。 |
| `next_cursor` | `str \| None` | 作为 `cursor` 传入以获取下一页；当前页为最后一页时为 None。 |
| `truncated` | `bool` | 当本页之后还有更多人时为 True（此时已设置 `next_cursor`）。 |

<a id="grantspending_for_me"></a>

## `grants.pending_for_me`

通过一条语句返回调用方所管理的命名空间中的全部待处理请求。

`POST /v1/grants.pending_for_me` · MCP `loom_grants_pending_for_me` · 角色 `viewer` · 读操作 · 未列在 MCP `all` 工具集中

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `limit` | `int` | `500` | 最多返回这么多条请求，按时间从新到旧排列；取值范围为 1 到 2,000。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[_PendingForMeEntry]` | 调用方所管理的命名空间中待处理的加入或提权请求，按时间从新到旧排列；匿名调用方得到空列表。 |

<a id="grantsrevoke"></a>

## `grants.revoke`

撤销某个主体在命名空间上的授权。

`POST /v1/grants.revoke` · MCP `loom_grants_revoke` · 角色 `admin` · 幂等 · 有审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `subject` | `str` | 必填 | 要撤销谁的授权：登录名、电子邮件或服务账号的 `sub`；该用户在每种已验证写法下的记录都会被删除，待处理的请求会被拒绝。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `revoked` | `bool` | 找到并撤销了该主体的任一授权记录时为 true；该主体没有授权记录时为 false。 |
| `revoked_at` | `datetime \| None` | 撤销写入的时间（UTC）；未撤销任何内容时为 None。 |

<a id="grantsshare_agent"></a>

## `grants.share_agent`

允许调用方所属信任域内的另一个 agent 读取或写入调用方自己的命名空间。

`POST /v1/grants.share_agent` · MCP `loom_grants_share_agent` · 角色 `writer` · 幂等 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 调用方 agent 自己的命名空间，也是它唯一可以共享的命名空间。 |
| `grantee` | `str` | 必填 | 要与之共享的同一信任域内的 agent，使用其控制平面中的名称。 |
| `role` | `Literal['viewer', 'writer']` | `'viewer'` | 该 agent 在此命名空间中可执行的操作：`viewer` 可读取，`writer` 还可写入。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `namespace` | `str` | 该 op 读取或写入的命名空间。 |
| `subject` | `str` | 授权记录所属的主体，格式为 `sa:<trust>:<agent>`。 |
| `role` | `Literal['viewer', 'writer']` | 该 agent 当前生效的角色。 |
| `granted_at` | `datetime` | 授权记录的写入时间（UTC）。 |

<a id="grantsunshare_agent"></a>

## `grants.unshare_agent`

收回调用方借给同一信任范围内另一个 agent 的授权。

`POST /v1/grants.unshare_agent` · MCP `loom_grants_unshare_agent` · 角色 `writer` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 调用方 agent 自己的命名空间。 |
| `grantee` | `str` | 必填 | 同一信任范围内、要撤销其授权的 agent。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `revoked` | `bool` | 当该 agent 持有授权且已被撤销时为 True。 |
| `revoked_at` | `datetime \| None` | 撤销写入的时间（UTC）；未撤销任何授权时为 None。 |

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