Design a Custom Role System

As organizations grow, access control becomes more complex than assigning everyone broad administrator access. API7 Gateway lets you design a custom role system by combining users, roles, permission policies, and permission boundaries.

This guide explains how to design that system so it stays understandable, secure, and maintainable as your teams and environments grow.

Start with an Access Model

Before you create any roles, define the operating model you want your permission policies to support:

• Which teams need access to API7 Gateway.
• Which environments they should manage, such as dev, test, staging, and production.
• Which actions they should be allowed to perform, such as view-only, deploy, operate, or administer users.
• Which resources must remain tightly controlled, such as licenses, organization settings, credentials, and production Gateway Groups.

This keeps the role system aligned with real responsibilities instead of mirroring org charts too literally.

Core Design Principles

Grant least privilege first

Start with the narrowest permission set that lets a team do its job. Expand later only when there is a demonstrated operational need.

Good starting patterns include:

• Read-only roles for audit, support, and compliance workflows.
• Separate roles for non-production and production operations.
• Separate IAM administration from gateway traffic management.

Prefer reusable permission policies

Design small, reusable permission policies and attach them to multiple roles where appropriate. This keeps your access model easier to review and update.

For example, you might create separate policies for:

• Read-only access to production Gateway Groups.
• Full access to test Gateway Groups.
• User and role administration.
• Audit-log viewing.

Then compose those policies into roles that match real responsibilities.

Use labels to scale

When you manage many Gateway Groups, services, or teams, avoid hard-coding every resource ID into every policy. Instead, use labels and label-based conditions so policies can scale with less maintenance.

Examples:

• env=production
• team=payments
• region=eu

This makes it easier to grow from a few environments to dozens without rewriting every role.

Separate role design from role assignment

Not everyone who assigns roles should also be able to design or edit them. In many organizations, a small number of trusted administrators define policies and roles, while team leads or delegated admins only assign approved roles to users.

This separation reduces the risk of accidental privilege escalation.

Use permission boundaries for safe delegation

A permission boundary limits the maximum permissions a user can have, even if broader roles are attached later. This is useful when you want to delegate some administrative work without allowing unrestricted growth of privileges.

Common examples include:

• Contractors who should never access production.
• Team leads who can manage users only within a limited scope.
• Temporary admins for migrations or incident response.

Recommended Role Layers

Many teams benefit from thinking in layers instead of creating one role per person.

Platform administrators

These users manage the overall platform and organization-level settings.

Typical capabilities:

• Manage users, roles, permission policies, and organization settings.
• Manage all Gateway Groups.
• Review audit logs and critical platform state.

Keep this group small.

Environment operators

These users manage traffic resources in specific environments.

Typical patterns:

• Developers: full access in dev and test, no production write access.
• Release engineers: write access in staging and controlled access in production.
• SREs: operational access across environments, with tighter restrictions on IAM resources.

Read-only users

These users need visibility but not change permissions.

Common examples:

• Auditors
• Support engineers
• Security reviewers

Delegated administrators

These users manage a bounded subset of IAM or gateway resources.

Common examples:

• Team leads who assign pre-approved roles to their team.
• Role managers who can maintain users and roles but not modify traffic configuration.

Example Design Patterns

Environment isolation

Create separate permission policies for each environment and then combine them into roles.

Example:

• production-readonly
• test-full-access
• staging-full-access

A developer role might combine test-full-access and staging-full-access, while an approver role might combine production-readonly and staging-full-access.

Team-based management

If multiple teams share the same API7 Gateway deployment, use labels to isolate ownership.

Example:

• Gateway Groups or services labeled team=payments
• Policies that allow access only when that label matches

This lets each team operate within its own boundary even in a shared platform.

Central role management with local delegation

Use a small set of central administrators to define policies and roles. Then let team leads assign approved roles to users within their own team, ideally with permission boundaries to prevent overreach.

This is often easier to govern than allowing every team to invent its own access model from scratch.

Review Checklist

Before adopting a role design, review it against these questions:

• Does each role map to a real operational responsibility?
• Can any role modify production when it only needs read access?
• Can IAM administrators also change gateway traffic configuration when they should not?
• Are resource scopes narrow enough, or do they rely on unnecessary wildcards?
• Can labels reduce duplication across policies?
• Should any users have permission boundaries applied?
• Is there a defined review cadence for role and policy assignments?

Operational Practices

Keep the role system healthy over time:

• Review role assignments regularly and remove unused access.
• Prefer changing policy attachments over creating many near-duplicate roles.
• Audit broad wildcard permissions and justify them explicitly.
• Test major policy changes with a non-root user before broad rollout.
• Record ownership for each shared role and permission policy.

When to Create a New Role

Create a new role only when at least one of these is true:

• A team has a durable responsibility that existing roles do not match.
• A different environment scope is required.
• Separation of duties is needed for compliance or risk reduction.
• A reusable policy combination will be assigned to multiple users.

If the need is temporary or user-specific, a permission boundary or a direct assignment change may be better than inventing another long-lived role.

Next Steps

• Create a Custom Role — build a concrete role by combining permission policies.
• Role-Based Access Control — understand how access is evaluated.
• Permission Policies and Boundaries — author policy JSON and boundaries.
• Permission Policy Examples — adapt ready-made examples for your organization.