Operation details
GET /v1/custom-rbac/grants
Page through active or revoked custom-role grants
- operationId
listTenantCustomRoleGrants- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Description (from the contract)
The signed cursor freezes grant creation and revocation state at the durable commit-ordered database watermark captured by the first page.
Parameters
listTenantCustomRoleGrants Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | — |
|---|
role_id | query | string(uuid) | No | — |
|---|
subject_user_id | query | string(uuid) | No | — |
|---|
state | query | string: active / revoked / all | No | — |
|---|
Responses
listTenantCustomRoleGrants Responses| Status | Description |
|---|
200 | Stable page of custom-role grants. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/custom-rbac/grants
Assign the current role revision to another active tenant member
- operationId
assignTenantCustomRole- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Parameters
assignTenantCustomRole Parameters| Name | In | Type | Required | Description |
|---|
If-Match | header | string | Yes | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Step-Up-Proof | header | string | No | 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. |
|---|
Request body
application/json · Required：Yes
assignTenantCustomRole Request body| Name | Type | Required | Description |
|---|
role_id | string(uuid) | Yes | — |
|---|
subject_user_id | string(uuid) | Yes | — |
|---|
Responses
assignTenantCustomRole Responses| Status | Description |
|---|
201 | Grant created, or the original response replayed. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.428 A precondition is missing: read the resource and send If-Match (or the required proof).503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/custom-rbac/grants/{grant_id}/revoke
Append a custom-role grant revocation fact
- operationId
revokeTenantCustomRoleGrant- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Parameters
revokeTenantCustomRoleGrant Parameters| Name | In | Type | Required | Description |
|---|
grant_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Step-Up-Proof | header | string | No | 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. |
|---|
Responses
revokeTenantCustomRoleGrant Responses| Status | Description |
|---|
200 | Revocation appended, or the original response replayed. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.428 A precondition is missing: read the resource and send If-Match (or the required proof).503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/custom-rbac/permissions
List the tenant-delegable permission catalog
- operationId
listTenantDelegablePermissions- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Responses
listTenantDelegablePermissions Responses| Status | Description |
|---|
200 | Delegable permission catalog. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/custom-rbac/roles
Page through custom roles in the authenticated tenant scope
- operationId
listTenantCustomRoles- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Description (from the contract)
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.
Parameters
listTenantCustomRoles Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | — |
|---|
include_deactivated | query | boolean | No | — |
|---|
Responses
listTenantCustomRoles Responses| Status | Description |
|---|
200 | Stable page of custom roles. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/custom-rbac/roles
Create a custom role and its first immutable revision
- operationId
createTenantCustomRole- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Parameters
createTenantCustomRole Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Step-Up-Proof | header | string | No | 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. |
|---|
Request body
application/json · Required：Yes
createTenantCustomRole Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
permissions | array<string> | Yes | — |
|---|
Responses
createTenantCustomRole Responses| Status | Description |
|---|
201 | Custom role created, or the original response replayed. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.428 A precondition is missing: read the resource and send If-Match (or the required proof).503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/custom-rbac/roles/{role_id}
Get a custom role in the authenticated tenant scope
- operationId
getTenantCustomRole- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Description (from the contract)
Unknown and cross-tenant role IDs return the same 404 response.
Parameters
getTenantCustomRole Parameters| Name | In | Type | Required | Description |
|---|
role_id | path | string(uuid) | Yes | — |
|---|
Responses
getTenantCustomRole Responses| Status | Description |
|---|
200 | Custom role detail. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/custom-rbac/roles/{role_id}/deactivate
Deactivate a custom role with compare-and-swap
- operationId
deactivateTenantCustomRole- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Parameters
deactivateTenantCustomRole Parameters| Name | In | Type | Required | Description |
|---|
role_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Step-Up-Proof | header | string | No | 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. |
|---|
Responses
deactivateTenantCustomRole Responses| Status | Description |
|---|
200 | Custom role detail. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.428 A precondition is missing: read the resource and send If-Match (or the required proof).503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/custom-rbac/roles/{role_id}/publish
Publish a new permission revision with compare-and-swap
- operationId
publishTenantCustomRoleRevision- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Parameters
publishTenantCustomRoleRevision Parameters| Name | In | Type | Required | Description |
|---|
role_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Step-Up-Proof | header | string | No | 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. |
|---|
Request body
application/json · Required：Yes
publishTenantCustomRoleRevision Request body| Name | Type | Required | Description |
|---|
permissions | array<string> | Yes | — |
|---|
Responses
publishTenantCustomRoleRevision Responses| Status | Description |
|---|
200 | Custom role detail. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.428 A precondition is missing: read the resource and send If-Match (or the required proof).503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/custom-rbac/roles/{role_id}/rename
Rename a custom role with revision compare-and-swap
- operationId
renameTenantCustomRole- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity.roles.manage
Parameters
renameTenantCustomRole Parameters| Name | In | Type | Required | Description |
|---|
role_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal current role revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Step-Up-Proof | header | string | No | 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. |
|---|
Request body
application/json · Required：Yes
renameTenantCustomRole Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
Responses
renameTenantCustomRole Responses| Status | Description |
|---|
200 | Custom role detail. Fields：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 |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.428 A precondition is missing: read the resource and send If-Match (or the required proof).503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list