Roles and Custom Roles

Every organization member has one role that controls what they can do in the AISIX Cloud dashboard and AISIX Cloud Admin API. AISIX Cloud provides three built-in roles for common access patterns. Organizations that need finer control can define custom roles as named permission sets over the same resource vocabulary enforced by the API.

An organization role sets the member's baseline across every environment. When a member needs additional access in one environment, an owner can add an environment access grant without changing that baseline elsewhere.

Roles govern who can configure the gateway through the control plane. API key settings separately determine which models and tools a key can use and which budgets apply to its traffic.

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. Member role changes, member removal, and admin token creation remain owner-only.
member	Read-only access to the organization's resources. Audit events are not readable.

The Roles page lists each role and its enforced permissions. The page uses the same permission catalog that the API checks for every request.

Custom Roles

A custom role is a named set of read and write permissions on resources such as environments, models, API keys, guardrails, budgets, and audit events. It replaces the member's built-in baseline instead of extending it. A role that grants only read access to environments, for example, cannot list teams or view usage.

Typical uses include:

• 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 change members or billing.
• A read-mostly role with write access to one resource type, such as budgets.

Create and Assign

1. As an organization admin or owner, open Roles and select New role.
2. Enter a permanent lowercase name such as auditor. Members reference the role by name, so create a new role when you need a different name.
3. Select the permissions the role grants and save it.
4. As an organization owner, assign the role on the Members page.

For directory-managed access, a custom role can serve as the default role or the target of a SCIM group-to-role mapping. See directory sync.

To change a custom role's description or permissions, open Roles and select Edit. To remove it, select Delete after clearing the references described in Rules and Limits. Built-in roles cannot be edited or deleted.

Environment-Scoped Access

A member's organization role applies across the whole organization. An environment access grant adds another role inside one environment. It can extend but cannot narrow the member's 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 to resources inside an environment combines the permissions from the organization role and any grant for that environment.
• Grants have no effect outside their environment. The organization role alone governs resources in every other environment and organization-level resources such as members, teams, settings, billing, and custom roles.
• Grants cover resources inside the environment, not the environment object itself. An environment-scoped admin cannot rename or delete the environment.
• Grants can target admin, member, or any custom role. They cannot target owner.
• Owners already have full access, so they cannot receive grants. Only owners can edit a member's grants.
• Deleting an environment removes the grants that pointed into it.

Manage grants on the Members page: expand Environment access on a member row, add, change, or remove environment and role pairs, and save.

Use the API

Use an admin token with read scope to list roles and environment access grants. A token with write scope can create, update, or delete roles. Only an organization owner can assign roles or replace environment access grants.

Set the AISIX Cloud Admin API base URL and token before running the examples:

# AISIX_CP includes /api and has no trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

Create and Assign a Custom Role

Create an organization-scoped role with the permissions it should grant:

curl -sS -X POST "${AISIX_CP}/roles" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auditor",
    "description": "Read-only audit access",
    "permissions": [
      {
        "action": "read",
        "resource": "audit"
      },
      {
        "action": "read",
        "resource": "usage"
      }
    ]
  }'

An owner can assign the role to a member. Use the member's user_id from GET /members:

export USER_ID="2c7d6e5f-4a3b-4c2d-8e1f-9a0b1c2d3e4f"

curl -sS -X PATCH "${AISIX_CP}/members/${USER_ID}" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"role": "auditor"}'

Update or Delete a Custom Role

Supplying permissions replaces the role's complete permission set:

curl -sS -X PATCH "${AISIX_CP}/roles/auditor" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      {
        "action": "read",
        "resource": "audit"
      }
    ]
  }'

After clearing every reference described in Rules and Limits, delete the role:

curl -sS -X DELETE "${AISIX_CP}/roles/auditor" \
  -H "Authorization: Bearer ${AISIX_TOKEN}"

Deleting a role that is still referenced returns 409 ROLE_IN_USE. Member assignments and environment grants can be cleared through the AISIX Cloud Admin API. Pending invitations and directory sync references must currently be cleared in the dashboard.

Manage Environment Access Grants

Environment access routes use the membership id returned by GET /members, not the member's user_id. List the member's current grants before replacing them:

export MEMBER_ID="8f3b2a1c-9d4e-4f6a-b7c8-1e2d3f4a5b6c"

curl -sS "${AISIX_CP}/members/${MEMBER_ID}/role_bindings" \
  -H "Authorization: Bearer ${AISIX_TOKEN}"

An owner can replace the complete grant set. Each environment can appear at most once:

curl -sS -X PUT "${AISIX_CP}/members/${MEMBER_ID}/role_bindings" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": [
      {
        "env_id": "6b1c2c1e-0000-4000-8000-000000000002",
        "role": "admin"
      }
    ]
  }'

Send an empty bindings array to remove every environment access grant. Changes may take up to 30 seconds to propagate across control-plane replicas.

See the AISIX Cloud Admin API Reference for response schemas and error details.

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 custom role cannot be deleted while it is assigned to a member or pending invitation, used as the directory sync default role or the target of a group-to-role mapping, or used in an environment access grant.
• Before deleting a custom role, reassign members, revoke pending invitations, clear any references under Default role and Group → role mappings in Directory sync (SCIM), and remove the role from Environment access grants.
• Permission changes take effect for every member holding the role, but may take up to 30 seconds to propagate across control-plane replicas.

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.