Role-Based Access Control (RBAC)

API7 Gateway uses Role-Based Access Control (RBAC) to govern what users can do inside the control plane. A user's access is determined by the roles assigned to them and the permission policies attached to those roles. This model ensures that users only receive the access they need to perform their specific duties, reducing the risk of unauthorized configuration changes.

How roles and policies work together

• Roles organize users into groups with specific levels of access. A single role can have multiple permission policies attached to it.
• Permission policies define exactly which actions are allowed or denied on which resources. A single policy can be attached to multiple roles, or applied directly to individual users as a permission boundary.

A user's effective permissions are the combined result of their assigned roles and any permission boundaries. For full details on how policies are authored, see Permission Policies and Boundaries.

Built-in role: Super Admin

API7 Gateway ships with a single pre-defined role: Super Admin.

• Super Admin is bound to the built-in super-admin-permission-policy, which grants full access to every action on every resource.
• Super Admin and its associated built-in policy are non-editable to protect the integrity of the system.
• The initial administrator account created during installation is permanently tied to the Super Admin role and cannot be downgraded.

All other roles must be created as custom roles — there are no other built-in roles.

Custom roles

You can create custom roles for fine-grained access control. Common patterns include:

• Environment isolation — Separate roles for development, testing, staging, and production gateway groups, so that engineers can modify non-production environments without touching production.
• Team-based access — A "Payments Team" role that can manage services and routes within a specific gateway group but cannot view or modify services owned by other teams.
• Function-based access — A "Security Auditor" role with read-only access to audit logs, consumers, and credentials across all gateway groups.
• Delegated administration — A "Role Manager" role that can manage users and roles but cannot modify gateway traffic configuration.

Create a custom role

1. In the API7 Dashboard, navigate to Organization > Roles.
2. Click Create Role.
3. Provide a name and description for the role.
4. Attach one or more permission policies to the role.
5. Save the role.

Custom roles can be updated or deleted. A role that is currently assigned to users cannot be deleted directly — first detach the role from all users, then delete it.

Assign roles to users

Once a role exists, you can assign it to one or more users.

1. Navigate to Organization > Users.
2. Select an existing user or invite a new one.
3. Attach one or more roles to the user.
4. If single sign-on is enabled, you can map IdP groups or attributes to API7 roles instead of assigning them manually. See SSO for Dashboard for role-mapping rules.

Authorization model

When a user performs an action, API7 evaluates the request against every policy attached to every role the user holds, plus any permission boundary applied directly to the user. Access is granted only when all of the following are true:

1. At least one assigned role permits the action.
2. Any permission boundary (if set on the user) also permits the action.
3. No role or boundary explicitly denies the action.

A single deny statement blocks access, even if other policies would allow it. This "deny overrides allow" principle is fundamental to safe delegation.

Best practices

• Least privilege — Grant users only the minimum permissions needed. Narrow resource scopes with gateway group IDs, service template IDs, or labels instead of using wildcards.
• Separate policy management from policy consumption — Give a small number of trusted administrators the right to create and update roles and policies, while most users only receive pre-approved roles.
• Use labels for scale — When you manage many gateway groups or services, use label-based conditions in permission policies rather than enumerating resource IDs one by one.
• Review assignments regularly — Audit role assignments and permission policies on a schedule, and remove access as soon as it is no longer needed.

Next steps

• Permission Policies and Boundaries — learn the full JSON syntax for authoring policies.
• Permission Policy Actions and Resources — browse the complete catalog of supported actions and resource ARNs.
• Permission Policy Examples — ready-to-adapt example policies for common scenarios.
• Review Audit Logs — track administrative actions and permission changes.