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 published services.

Dashboard

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>/publishedservice/<.*>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ],
      "effect": "allow"
    }
  ]
}

Admin API

curl -k "https://localhost:7443/api/permission_policies" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-readonly",
    "desc": "Read-only access to the production gateway group",
    "policy_document": {
      "statement": [
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>"
          ],
          "actions": [
            "<.*>Get<.*>"
          ],
          "effect": "allow"
        },
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>/publishedservice/<.*>"
          ],
          "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 published services.

Dashboard

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>/publishedservice/<.*>"
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    }
  ]
}

Admin API

curl -k "https://localhost:7443/api/permission_policies" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-full-access",
    "desc": "Full access to the test gateway group",
    "policy_document": {
      "statement": [
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>"
          ],
          "actions": [
            "<.*>"
          ],
          "effect": "allow"
        },
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>/publishedservice/<.*>"
          ],
          "actions": [
            "<.*>"
          ],
          "effect": "allow"
        }
      ]
    }
  }'

Step 3: Create the Custom Role

Create a role that combines the two permission policies.

Dashboard

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.

Admin API

Create the role:

curl -k "https://localhost:7443/api/roles" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Team Member",
    "desc": "Read-only access to production and full access to test"
  }'

Then attach the permission policies to the role by using the role and policy IDs returned by the API:

curl -k "https://localhost:7443/api/roles/<role-id>/attach_permission_policies" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    "<production-policy-id>",
    "<test-policy-id>"
  ]'

Step 4: Assign the Role to a User

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

Dashboard

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.

Admin API

Update the user's assigned roles with the target role ID:

curl -k "https://localhost:7443/api/users/<user-id>/assigned_roles" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": [
      "<role-id>"
    ]
  }'

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

• Role-Based Access Control — understand how roles, users, and policies fit together.
• Permission Policies and Boundaries — learn the JSON syntax and evaluation model.
• Permission Policy Actions and Resources — browse the supported actions and resource patterns.
• Design a Custom Role System — plan a scalable role model for larger organizations.