接口详情
GET /v1/custom-rbac/grants
Page through active or revoked custom-role grants
- operationId
listTenantCustomRoleGrants- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
说明（契约原文）
The signed cursor freezes grant creation and revocation state at the durable commit-ordered database watermark captured by the first page.
参数
listTenantCustomRoleGrants 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
role_id | query | string(uuid) | 否 | — |
|---|
subject_user_id | query | string(uuid) | 否 | — |
|---|
state | query | string: active / revoked / all | 否 | — |
|---|
响应
listTenantCustomRoleGrants 响应| 状态码 | 说明 |
|---|
200 | Stable page of custom-role grants. 字段：data: array<Grant> page: Page |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/custom-rbac/grants
Assign the current role revision to another active tenant member
- operationId
assignTenantCustomRole- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
参数
assignTenantCustomRole 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
If-Match | header | string | 是 | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Step-Up-Proof | header | string | 否 | Opaque 32-byte base64url MFA proof. Required when the affected permission set contains a catalog entry with step_up_required=true. The server consumes it in the RBAC transaction and binds the use to the operation, authenticated tenant actor and session, target role, subject or grant, expected revision, normalized business payload, and idempotency key. Reusing the proof for a different logical mutation is rejected even when request IDs match. |
|---|
请求体
application/json · 必填：是
assignTenantCustomRole 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
role_id | string(uuid) | 是 | — |
|---|
subject_user_id | string(uuid) | 是 | — |
|---|
响应
assignTenantCustomRole 响应| 状态码 | 说明 |
|---|
201 | Grant created, or the original response replayed. 字段：data: Grant |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
404 | Resource is absent or outside the authenticated tenant |
|---|
409 | Idempotency, revision, name, lifecycle, or immutability conflict |
|---|
413 | Request body exceeded the configured limit |
|---|
428 | A valid bound and unconsumed step-up proof is required |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/custom-rbac/grants/{grant_id}/revoke
Append a custom-role grant revocation fact
- operationId
revokeTenantCustomRoleGrant- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
参数
revokeTenantCustomRoleGrant 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
grant_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Step-Up-Proof | header | string | 否 | Opaque 32-byte base64url MFA proof. Required when the affected permission set contains a catalog entry with step_up_required=true. The server consumes it in the RBAC transaction and binds the use to the operation, authenticated tenant actor and session, target role, subject or grant, expected revision, normalized business payload, and idempotency key. Reusing the proof for a different logical mutation is rejected even when request IDs match. |
|---|
响应
revokeTenantCustomRoleGrant 响应| 状态码 | 说明 |
|---|
200 | Revocation appended, or the original response replayed. 字段：data: Revocation |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
404 | Resource is absent or outside the authenticated tenant |
|---|
409 | Idempotency, revision, name, lifecycle, or immutability conflict |
|---|
428 | A valid bound and unconsumed step-up proof is required |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/custom-rbac/permissions
List the tenant-delegable permission catalog
- operationId
listTenantDelegablePermissions- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
响应
listTenantDelegablePermissions 响应| 状态码 | 说明 |
|---|
200 | Delegable permission catalog. 字段：data: array<Permission> |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/custom-rbac/roles
Page through custom roles in the authenticated tenant scope
- operationId
listTenantCustomRoles- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
说明（契约原文）
The signed cursor is bound to the authenticated scope and include_deactivated filter, and freezes role creation, revision, and deactivation state at a durable commit-ordered database watermark from the first page.
参数
listTenantCustomRoles 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
include_deactivated | query | boolean | 否 | — |
|---|
响应
listTenantCustomRoles 响应| 状态码 | 说明 |
|---|
200 | Stable page of custom roles. 字段：data: array<Role> page: Page |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/custom-rbac/roles
Create a custom role and its first immutable revision
- operationId
createTenantCustomRole- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
参数
createTenantCustomRole 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Step-Up-Proof | header | string | 否 | Opaque 32-byte base64url MFA proof. Required when the affected permission set contains a catalog entry with step_up_required=true. The server consumes it in the RBAC transaction and binds the use to the operation, authenticated tenant actor and session, target role, subject or grant, expected revision, normalized business payload, and idempotency key. Reusing the proof for a different logical mutation is rejected even when request IDs match. |
|---|
请求体
application/json · 必填：是
createTenantCustomRole 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
permissions | array<string> | 是 | — |
|---|
响应
createTenantCustomRole 响应| 状态码 | 说明 |
|---|
201 | Custom role created, or the original response replayed. 字段：data: Role |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
409 | Idempotency, revision, name, lifecycle, or immutability conflict |
|---|
413 | Request body exceeded the configured limit |
|---|
422 | A requested permission is not tenant delegable |
|---|
428 | A valid bound and unconsumed step-up proof is required |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/custom-rbac/roles/{role_id}
Get a custom role in the authenticated tenant scope
- operationId
getTenantCustomRole- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
说明（契约原文）
Unknown and cross-tenant role IDs return the same 404 response.
参数
getTenantCustomRole 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
role_id | path | string(uuid) | 是 | — |
|---|
响应
getTenantCustomRole 响应| 状态码 | 说明 |
|---|
200 | Custom role detail. 字段：data: Role |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
404 | Resource is absent or outside the authenticated tenant |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/custom-rbac/roles/{role_id}/deactivate
Deactivate a custom role with compare-and-swap
- operationId
deactivateTenantCustomRole- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
参数
deactivateTenantCustomRole 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
role_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Step-Up-Proof | header | string | 否 | Opaque 32-byte base64url MFA proof. Required when the affected permission set contains a catalog entry with step_up_required=true. The server consumes it in the RBAC transaction and binds the use to the operation, authenticated tenant actor and session, target role, subject or grant, expected revision, normalized business payload, and idempotency key. Reusing the proof for a different logical mutation is rejected even when request IDs match. |
|---|
响应
deactivateTenantCustomRole 响应| 状态码 | 说明 |
|---|
200 | Custom role detail. 字段：data: Role |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
404 | Resource is absent or outside the authenticated tenant |
|---|
409 | Idempotency, revision, name, lifecycle, or immutability conflict |
|---|
413 | Request body exceeded the configured limit |
|---|
422 | A requested permission is not tenant delegable |
|---|
428 | A valid bound and unconsumed step-up proof is required |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/custom-rbac/roles/{role_id}/publish
Publish a new permission revision with compare-and-swap
- operationId
publishTenantCustomRoleRevision- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
参数
publishTenantCustomRoleRevision 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
role_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Step-Up-Proof | header | string | 否 | Opaque 32-byte base64url MFA proof. Required when the affected permission set contains a catalog entry with step_up_required=true. The server consumes it in the RBAC transaction and binds the use to the operation, authenticated tenant actor and session, target role, subject or grant, expected revision, normalized business payload, and idempotency key. Reusing the proof for a different logical mutation is rejected even when request IDs match. |
|---|
请求体
application/json · 必填：是
publishTenantCustomRoleRevision 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
permissions | array<string> | 是 | — |
|---|
响应
publishTenantCustomRoleRevision 响应| 状态码 | 说明 |
|---|
200 | Custom role detail. 字段：data: Role |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
404 | Resource is absent or outside the authenticated tenant |
|---|
409 | Idempotency, revision, name, lifecycle, or immutability conflict |
|---|
413 | Request body exceeded the configured limit |
|---|
422 | A requested permission is not tenant delegable |
|---|
428 | A valid bound and unconsumed step-up proof is required |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/custom-rbac/roles/{role_id}/rename
Rename a custom role with revision compare-and-swap
- operationId
renameTenantCustomRole- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：identity.roles.manage
参数
renameTenantCustomRole 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
role_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | — |
|---|
X-Step-Up-Proof | header | string | 否 | Opaque 32-byte base64url MFA proof. Required when the affected permission set contains a catalog entry with step_up_required=true. The server consumes it in the RBAC transaction and binds the use to the operation, authenticated tenant actor and session, target role, subject or grant, expected revision, normalized business payload, and idempotency key. Reusing the proof for a different logical mutation is rejected even when request IDs match. |
|---|
请求体
application/json · 必填：是
renameTenantCustomRole 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
响应
renameTenantCustomRole 响应| 状态码 | 说明 |
|---|
200 | Custom role detail. 字段：data: Role |
|---|
400 | Strict header, query, path, or JSON validation failed |
|---|
401 | Authentication is required |
|---|
403 | Tenant session or delegation permission was denied |
|---|
404 | Resource is absent or outside the authenticated tenant |
|---|
409 | Idempotency, revision, name, lifecycle, or immutability conflict |
|---|
413 | Request body exceeded the configured limit |
|---|
422 | A requested permission is not tenant delegable |
|---|
428 | A valid bound and unconsumed step-up proof is required |
|---|
408 | Caller cancelled the request |
|---|
502 | Storage returned invalid facts or the response exceeded its bound |
|---|
503 | Storage or a required dependency is unavailable |
|---|
504 | Server-side operation deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表