Delete Custom Role
DELETE /roles/{role_name}
DELETE /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 <= 64Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "$AISIX_CP/roles/$ROLE_NAME" \ -H "Authorization: Bearer $AISIX_TOKEN"Deleted
{
"deleted": true,
"name": "string"
}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"
}
}The role is still referenced.
{
"error": {
"code": "ROLE_IN_USE",
"message": "role is still referenced by 1 pending invitation(s); remove every reference before deleting"
}
}Complete operation details and schema variants
DELETE /roles/{role_name}
Delete Custom Role
Delete a custom role. Built-in roles cannot be deleted. A custom role must first be removed from members, pending invitations, directory-sync settings, and environment role bindings. Member assignments and environment bindings can be cleared through this API. Pending invitations and directory-sync role settings must currently be cleared in the dashboard before retrying.
Parameters
role_name(path, string, required): Custom role name.
Responses
-
200: Deleted -
deleted(boolean, required): Alwaystrueon success. -
name(string, required): Deleted custom role name. -
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 toDELETE /roles/{role_name}, response 400 above. -
403: Authenticated request is not permitted. Response fields (application/json): identical toDELETE /roles/{role_name}, response 400 above. -
404: Resource not found. Response fields (application/json): identical toDELETE /roles/{role_name}, response 400 above. -
409: The role is still referenced. Response fields (application/json): identical toDELETE /roles/{role_name}, response 400 above.
cURL
curl -X DELETE '$AISIX_CP/roles/{role_name}' -H 'Authorization: Bearer $AISIX_TOKEN'