尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
grants 操作
每个 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。 |