Update Custom Role
PATCH /roles/{role_name}
PATCH /roles/{role_name}Interactive request editor loads with JavaScript.
Authorization
BearerAdminToken Organization-scoped admin token. Read operations require a valid token, and write operations require a token with write permission.
In: header
Path Parameters
Custom role name.
^[a-z][a-z0-9_-]{1,63}$2 <= length <= 64Request Body
application/json
Custom role update body. Include at least one field. Supplying
permissions replaces the complete permission set. A null
description is ignored and is valid only when permissions
is also supplied.
1 <= propertiesResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "$AISIX_CP/roles/$ROLE_NAME" \ -H "Authorization: Bearer $AISIX_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Updated
{
"role": {
"id": "string",
"display_name": "string",
"description": "string",
"permissions": [
{
"action": "string",
"resource": "string",
"description": "string"
}
],
"is_builtin": true
}
}Request body or parameters failed validation.
{
"error": {
"code": "string",
"message": "string"
}
}Missing or invalid bearer.
{
"error": {
"code": "UNAUTHENTICATED",
"message": "no org context"
}
}Authenticated request is not permitted.
{
"error": {
"code": "CUSTOM_KEY_DISABLED",
"message": "custom API key values are disabled for this organization"
}
}Resource not found.
{
"error": {
"code": "NOT_FOUND",
"message": "provider key not found"
}
}Complete operation details and schema variants
PATCH /roles/{role_name}
Update Custom Role
Update a custom role's description or replace its permissions. The role name cannot change. Built-in roles cannot be updated. Permission changes can take up to 30 seconds to propagate across control-plane replicas.
Parameters
role_name(path, string, required): Custom role name.
Request body
Content type: application/json
description(string, optional): Human-readable purpose of the role.permissions(array, optional):- oneOf variant 1
permissions[].action(string, required):permissions[].resource(string, required): Resource family a custom role may read.- oneOf variant 2
permissions[].action(string, required):permissions[].resource(string, required): Resource family a custom role may manage.
Responses
-
200: Updated -
role(object, required): Built-in or organization-defined control-plane role. -
role.id(string, required): Built-in role ID or immutable custom role name. -
role.display_name(string, required): Role label displayed in the dashboard. -
role.description(string, required): Human-readable purpose of the role. -
role.permissions(array, required): -
role.permissions[].action(string, required): Permission action. The owner role uses*. -
role.permissions[].resource(string, required): Resource family. The owner role uses*. -
role.permissions[].description(string, required): Human-readable effect of the permission. -
role.is_builtin(boolean, required): Whether AISIX Cloud defines and protects the role. -
400: Request body or parameters failed validation. -
error(object, required): Error details. -
error.code(string, required): Machine-readable identifier. Examples:UNAUTHENTICATED,INVALID_REQUEST,MASTER_KEY_UNSET,INTERNAL. -
error.message(string, required): Human-readable explanation; safe to surface to operators. -
401: Missing or invalid bearer. Response fields (application/json): identical toPATCH /roles/{role_name}, response 400 above. -
403: Authenticated request is not permitted. Response fields (application/json): identical toPATCH /roles/{role_name}, response 400 above. -
404: Resource not found. Response fields (application/json): identical toPATCH /roles/{role_name}, response 400 above.
cURL
curl -X PATCH '$AISIX_CP/roles/{role_name}' -H 'Authorization: Bearer $AISIX_TOKEN'