Roles and Custom Roles

Every organization member holds one role that decides what they can do in the AISIX Cloud dashboard and Admin API. Three built-in roles cover the common cases, and organizations that need finer control can define custom roles — named permission sets over the same resource vocabulary the API enforces.

Roles govern the control plane (who can configure the gateway). What traffic an API key may send — models, tools, budgets — is governed by the key's own settings, not by the member's role.

Built-in Roles

Role	Access
owner	Full control, including billing, member role changes, member removal, and admin-token management.
admin	Read and write access to every resource. Owner-only operations (role changes, member removal, admin-token minting) stay out of reach.
member	Read-only access to the organization's resources. Audit events are not readable.

The Roles page lists each role with the exact permissions it enforces — the page renders the same catalog the API checks on every request, so what you see is what applies.

Custom Roles

A custom role is a named set of read / write permissions on resource types (environments, models, API keys, guardrails, budgets, audit events, and so on). A member holding a custom role can do exactly what the role grants — it replaces the built-in baseline rather than extending it. A role granting only read on environments cannot list teams or view usage.

Typical uses:

• an auditor role that reads the audit trail and usage but configures nothing;
• a gateway-operator role that manages models, provider keys, and guardrails but cannot touch members or billing;
• a read-mostly role with write access to one resource type, such as budgets.

Create and Assign

1. Open Roles and select New role (organization admins and owners).
2. Pick a name — a lowercase slug such as auditor. The name is permanent: members reference the role by name, so renaming would strand them. Create a new role instead.
3. Check the permissions the role grants and save.
4. Assign the role on the Members page (organization owners only), or map a directory group to it — see directory sync.

Custom roles can also be the target of a SCIM group → role mapping and the directory-sync default role.

Rules and Limits

• Custom role definitions can be created, edited, and deleted by admins and owners. Assigning any role to a member stays owner-only.
• A custom role can never grant more than the built-in admin role holds: owner-only operations are not grantable, and directory sync can never assign owner.
• A role still assigned to members cannot be deleted — reassign those members first.
• Permission changes to a role apply to every member holding it within seconds.

API

Manage roles programmatically with an 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"

Deleting a role that members still hold returns 409 ROLE_IN_USE.