Skip to main content
API7.ai Logo
Version: 3.10.x

Create a Custom Role

API7 Gateway ships with a single built-in role, Super Admin, which is intended for initial setup and emergency recovery. For day-to-day operations, create custom roles that grant only the permissions each user or team actually needs.

This guide walks through a common pattern:

  • Read-only access to a production Gateway Group.
  • Full access to a test Gateway Group.
  • One custom role that combines both permission policies.

Prerequisites​

Before you begin, ensure you have:

  • API7 Gateway is running and the Dashboard is accessible.
  • You have a token for a user that can manage roles and permission policies. See Obtain a Token from the Dashboard.
  • You have at least two Gateway Groups, such as test and production.
  • You know the target Gateway Group IDs or have labels that can be used in permission policies.

For policy syntax details, see Permission Policies and Boundaries.

Step 1: Create a Read-Only Policy for Production​

Create a permission policy that allows read-only access to the production Gateway Group and its services.

  1. In the Dashboard, go to Organization -> Permission Policies.
  2. Click Create Permission Policy.
  3. Enter a name such as production-readonly.
  4. In the policy editor, paste a policy similar to the following and replace the Gateway Group ID with your production group ID.
  5. Save the policy.
{
  "statement": [
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ],
      "effect": "allow"
    },
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>/service/<.*>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ],
      "effect": "allow"
    }
  ]
}

Step 2: Create a Full-Access Policy for Test​

Create a second policy that allows full access to the test Gateway Group and its services.

  1. In Organization -> Permission Policies, click Create Permission Policy again.
  2. Enter a name such as test-full-access.
  3. Paste a policy similar to the following and replace the Gateway Group ID with your test group ID.
  4. Save the policy.
{
  "statement": [
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>"
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    },
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>/service/<.*>"
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    }
  ]
}

Step 3: Create the Custom Role​

Create a role that combines the two permission policies.

  1. Go to Organization -> Roles.
  2. Click Create Role.
  3. Enter a name such as Development Team Member.
  4. Add a description such as Read-only access to production and full access to test.
  5. Attach the production-readonly and test-full-access permission policies.
  6. Save the role.

Step 4: Assign the Role to a User​

Assign the new custom role to a non-root user.

  1. Go to Organization -> Users.
  2. Select an existing user or invite a new one.
  3. Attach the Development Team Member role.
  4. Save the change.

Step 5: Validate the Role​

Sign in as the user who received the new role and verify the expected access:

  • In the production Gateway Group, the user can view resources but cannot modify them.
  • In the test Gateway Group, the user can create, update, and delete resources.
  • Outside those scopes, the user does not receive unintended access.

If you prefer to validate with the Admin API, sign in as that user, generate a token, and send test requests against production and test resources.

Common Patterns​

  • Environment-scoped operator: read-only in production, write access in non-production.
  • Role manager: manage users, roles, and permission policies without access to traffic configuration.
  • Auditor: read-only access to audit logs, gateway configuration, and credentials.
  • Team lead: manage only resources labeled for a specific team.

For additional examples, see Permission Policy Examples.

Next Steps​