跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

`grants` 操作

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

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

每个操作在 HTTP 上都是 POST /v1/<op>,在 MCP 上对应工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)会在传输层能够提供时,从令牌和 MCP 会话中填充;对于在单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们保留各自平面的 org)之外,所有操作的 org 都取该安装的 org,并且在部分操作上,其命名空间和 agent 也由安装填充;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并列在 ignored_args 中。

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)。

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)。

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)。

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] 调用方所管理的命名空间中待处理的加入或提权请求,按时间从新到旧排列;匿名调用方得到空列表。

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。

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)。

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。

这个页面有帮助吗?