角色与自定义角色

每个组织成员都持有一个角色，该角色决定其可以在 AISIX Cloud 控制台和 Admin API 中执行的操作。三个内置角色覆盖常见场景；需要更细粒度控制的组织可以定义自定义角色，即针对同一组 API 资源定义的命名权限集合。

角色管理的是控制面（谁可以配置网关）。API Key 可以发送哪些流量（模型、工具和预算）由 API Key 自身的设置决定，而不是由成员角色决定。

内置角色

角色	访问权限
`owner`	完全控制，包括账单、成员角色变更、移除成员和管理 Admin Token。
`admin`	对所有资源具有读写权限，但不能执行仅 owner 可执行的操作，例如变更角色、移除成员和创建 Admin Token。
`member`	对组织资源具有只读权限，不能读取审计事件。

Roles 页面会列出每个角色实际执行的精确权限。该页面展示的权限目录与 API 每次请求检查的目录相同，因此页面中的内容就是实际生效的权限。

自定义角色

自定义角色是针对资源类型（环境、模型、API Key、安全护栏、预算、审计事件等）定义的 read / write 权限集合。持有自定义角色的成员只能执行角色授予的操作；自定义角色会替换内置基线，而不是在内置基线上扩展。例如，只对 environments 授予 read 的角色不能列出团队或查看用量。

常见用途包括：

只读审计记录和用量、但不配置任何内容的 auditor 角色；
管理模型、服务提供方密钥和安全护栏、但不能操作成员或账单的 gateway-operator 角色；
以只读为主、仅对一种资源（例如预算）授予写权限的角色。

创建和分配

打开 Roles，选择 New role（组织管理员和 owner 可执行）。
选择名称，例如小写 slug auditor。名称是永久的：成员按名称引用角色，因此重命名会使引用失效。请改为创建新角色。
选择角色授予的权限并保存。
在 Members 页面分配角色（仅组织 owner 可执行），或将目录组映射到该角色，请参阅目录同步。

自定义角色也可以作为 SCIM 组到角色映射和目录同步默认角色的目标。

环境范围访问

成员的角色通常适用于整个组织。环境访问授权可以进一步细化访问范围。每条授权都会在单个环境内为成员额外授予一个角色，并叠加在其组织角色之上，例如“仅拥有生产环境的 admin 权限”。

成员对环境资源的最终访问权限是组织角色与该环境授权的并集（取权限更宽的一方）。
授权在其所属环境之外不生效：组织级资源（成员、团队、设置、账单和自定义角色）以及其他环境仍只使用组织角色判断权限。
授权只覆盖环境内部的资源，不包含环境对象本身；环境范围的 admin 不能重命名或删除环境。
授权可以指向 admin、member 或任意自定义角色，但不能指向 owner。
owner 无法获得授权（因为其已经拥有全部权限），且只有 owner 可以编辑成员的授权。
删除环境时，指向该环境的授权也会被删除；被授权引用的自定义角色不能删除。

在 Members 页面管理授权：展开成员行中的 Environment access，添加环境和角色，然后保存。也可以通过 API 管理：

# 读取成员授权（成员 ID 来自 GET /api/members）
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://<your-host>/api/members/<member_id>/role_bindings"

# 替换全部授权（仅 owner 可执行）
curl -sS -X PUT "https://<your-host>/api/members/<member_id>/role_bindings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bindings":[{"env_id":"<environment-uuid>","role":"admin"}]}'

规则和限制

管理员和 owner 可以创建、编辑和删除自定义角色。向成员分配任何角色仍仅限 owner 执行。
自定义角色不能授予超过内置 admin 角色的权限。仅限 owner 的操作不能授予，目录同步也不能分配 owner。
仍有成员持有的角色不能删除，请先为这些成员重新分配角色。
角色权限变更会在数秒内应用到组织中持有该角色的所有成员。

API

使用 Admin Token 通过程序管理角色：

# List roles (built-ins + custom)
curl -sS -H "Authorization: Bearer $TOKEN" "https://<your-host>/api/roles"

# Create a custom role
curl -sS -X POST "https://<your-host>/api/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"auditor","description":"Read-only audit access","permissions":[{"action":"read","resource":"audit"},{"action":"read","resource":"usage"}]}'

# Update a role's permissions
curl -sS -X PATCH "https://<your-host>/api/roles/auditor" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissions":[{"action":"read","resource":"audit"}]}'

# Delete a role
curl -sS -X DELETE "https://<your-host>/api/roles/auditor" \
  -H "Authorization: Bearer $TOKEN"

如果删除仍有成员持有的角色，API 会返回 409 ROLE_IN_USE。

内置角色​

自定义角色​

创建和分配​

环境范围访问​

规则和限制​

API​

内置角色

自定义角色

创建和分配

环境范围访问

规则和限制

API