Origin Grants API
Origin 处于早期 beta 版阶段，后续可能发生变化。
一个授权将一个 principal 与一个代码仓库或 namespace 及一项权限绑定在一起。授权 API 可列出直接作用于某个 resource 上的授权、更新或插入某个 principal 持有的授权，并可将其删除，从而以代码的方式对访问权限变更进行脚本化和审核。写操作复用代码库权限 UI 背后的访问检查，并记录相同的 repository.access_changed 和 namespace.access_changed 审计事件。
这六个端点位于 Origin API 参考文档的 Grants 分组中：List Repository Grants、Upsert Repository Grant、Delete Repository Grant、List Namespace Grants、Upsert Namespace Grant 和 Delete Namespace Grant。它们共用 Origin API 的 base URL、身份验证、pagination 和错误模型。本页介绍其背后的概念。
Principals
每个授权只能指定一个 principal。
| Principal | Field | 标识对象 |
|---|---|---|
user | user.id | 一个 Cherri Code 用户，通过组织 API 所使用的 encoded user_… id 标识。 |
group | group.id | 一个 Cherri Code 群组，通过其 public grp_… id 标识：可以是 owner 所在团队拥有的群组，也可以是该团队所属组织中的群组，该 id 由 组织 API 的群组 route 以 publicId 返回。这些 route 所接受的 g_… id 是另一个 identifier。 |
teamGroup | teamGroup.kind | 所属团队的某个内置群组：members (全部团队成员) 或 admins (team admins) 。 |
团队群组的授权代表该内置群组中每个成员在该 resource 上拥有的最低权限。在 namespace 上，它就是团队的 namespace 最低权限；在代码仓库上，它是团队的 per-repository override，删除后该代码仓库将恢复为 namespace 最低权限。
用户必须属于 owner 所在的组织。群组必须是 owner 所在团队拥有的群组，或该团队所属组织中的 active 群组；即使团队尚未 linked 到组织，团队自有的群组也可以被授权。对于不存在的用户或群组，write 端点返回的结果与组织外部的用户或群组完全相同，因此响应绝不会透露某个 principal 是否存在。列表响应会省略那些已无法 resolve 到 active 用户、群组或所属团队的 principal。
权限
代码仓库授权与 namespace 授权使用不同的权限层级，二者均对应代码库权限 UI 提供的预设。
| 资源 | permission 取值 |
|---|---|
| 代码仓库 | read、write、admin |
| Namespace | PERMISSION_READ、PERMISSION_CONTRIBUTOR、PERMISSION_WRITE、PERMISSION_ADMIN |
PERMISSION_READ、PERMISSION_CONTRIBUTOR 和 PERMISSION_WRITE 会对该 namespace 下的内部代码仓库授予相应级别的权限，PERMISSION_ADMIN 则用于管理 namespace 本身。
若某项授权使用了自定义策略，列表响应会返回 custom (代码仓库) 或 PERMISSION_CUSTOM (namespace) 。更新或插入端点会拒绝这些取值并返回 InvalidArgument (HTTP 400) ；自定义策略不在授权 API 的处理范围内。
Scopes
授权 API 涉及四个 scope，均列在 Scopes 中：repository:settings:read 和 repository:settings:write 用于代码仓库授权，namespace:settings:read 和 namespace:settings:write 用于 namespace 授权。
app installations 可同时持有这四个 scope，因此机器人可使用安装访问令牌调用授权 API，用户访问令牌也同样适用。请求 :write scope 时，会一并授予对应的 :read scope。list 端点消耗 1 点，write 操作消耗 5 点，均计入 Rate limits 中的预算。
更新或插入与删除
更新或插入是一个 POST 请求，用于创建或替换 principal 在该 resource 上持有的授权。每个 principal 对每个 resource 只持有一个授权，因此重复发送同一请求不会改变已有的授权，而换用不同的 permission 则会替换先前的授权。删除操作在请求体中指定 principal，并返回 204 No Content。
一个 namespace 始终至少保留一名 admin。若某次更新或插入或删除会导致 owner 不再拥有任何 admin，则返回 FailedPrecondition (HTTP 400) 。