Roles and Custom Roles

Every organization member holds one role that decides what they can do in the AISIX Cloud control plane dashboard and AISIX Cloud 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. It 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.

Environment-Scoped Access

A member's organization role applies across the whole organization. An environment access grant adds one extra role inside a single environment, on top of the organization role. It cannot narrow the organization role.

For example, a member can keep read-only organization access while receiving an admin grant for the production environment. The grant adds write access to resources inside production; it does not remove the member's organization-level access elsewhere. Use a custom organization role when you need to reduce the baseline permissions that apply across the organization.

• Effective access on an environment's resources is the union of the organization role and any grant on that environment (most permissive wins).
• Grants have no effect outside their environment: organization-level surfaces (members, teams, settings, billing, custom roles) and other environments see only the organization role.
• Grants cover the resources inside the environment, never the environment object itself — an environment-scoped admin cannot rename or delete the environment.
• Grants can target admin, member, or any custom role — never owner.
• Owners cannot receive grants (they already hold full access), and only owners can edit a member's grants.
• Deleting an environment removes the grants that pointed into it; a custom role referenced by a grant cannot be deleted.

Manage grants on the Members page: expand Environment access on a member row, add rows (environment + role), and save. Over the API:

# Read a member's grants (member id from GET /api/members)
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://<your-host>/api/members/<member_id>/role_bindings"

# Replace the whole grant set (owner only)
curl -sS -X PUT "https://<your-host>/api/members/<member_id>/role_bindings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bindings":[{"env_id":"<environment-uuid>","role":"admin"}]}'

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 cannot be granted, 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.

Next Steps

Continue with SCIM Directory Sync when your identity provider should manage member and role assignments. To connect the gateway that serves environment resources, see Connect an AISIX Gateway.