User Management

API7 Enterprise provides built-in user management with role-based access control (RBAC). You can manage users, roles, and permission policies through the Dashboard or the Admin API.

Default Admin Account

When API7 Gateway starts for the first time, it creates a default administrator account:

• Username: admin
• Password: admin
• Role: super_admin

The super_admin role is a built-in role with full access to all resources and actions. Change the default password immediately after your first login for security.

User Lifecycle

Manage users by inviting them to your organization and assigning appropriate roles.

Invite a User

To invite a new user, send a POST request to the /api/invites endpoint.

curl -k "https://localhost:7443/api/invites" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer_jane",
    "password": "TemporaryPassword123!",
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  }'

List Users

To retrieve a list of all users:

curl -k "https://localhost:7443/api/users" -X GET \
  -H "X-API-KEY: ${API_KEY}"

Update a User

To update basic attributes of a user:

curl -k "https://localhost:7443/api/users/${USER_ID}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  }'

Assign Roles

Assign one or more roles to a user by updating their assigned roles.

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 '{
    "role_ids": ["role_id_1", "role_id_2"]
  }'

Delete a User

To remove a user from the organization:

curl -k "https://localhost:7443/api/users/${USER_ID}" -X DELETE \
  -H "X-API-KEY: ${API_KEY}"

User Fields

The user resource contains the following key fields:

Field	Type	Description
id	UUID	Auto-generated unique identifier for the user.
username	String	Unique username used for authentication.
name	String	Display name for the user.
email	String	User's email address.
provider	Enum	Authentication source: builtin (local), sso (OIDC/SAML), or scim (provisioned).
roles	Array	References to roles assigned to the user.
boundaries	Array	Permission policies attached directly to the user to restrict their effective permissions.

Roles

A role is a collection of permission policies that define what a user can do.

• Built-in Roles: API7 Gateway ships with a single built-in role, Super Admin, which is bound to the non-editable super-admin-permission-policy and grants full access to all resources. The initial administrator account is permanently tied to this role.
• Custom Roles: Create roles tailored to your organization's structure, such as api_provider, runtime_admin, or viewer. See Role-Based Access Control for design guidance.

Create a Custom Role

curl -k "https://localhost:7443/api/roles" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Provider",
    "desc": "Can manage services and routes but cannot delete them.",
    "policies": ["policy_id_1"]
  }'

Permission Policies

Permission policies define the fine-grained rules for access control. Each policy consists of one or more statements.

A statement includes:

• Effect: allow or deny.
• Resources: An array of ARN patterns (e.g., arn:api7:gateway:gatewaygroup/<.*>).
• Actions: An array of action strings in the form <namespace>:<Verb><Resource> (e.g., gateway:GetGatewayGroup, iam:InviteUser).
• Conditions: Optional constraints, such as matching labels (MatchLabel) or verifying string arrays (AllOfStrings).

See Permission Policies and Boundaries for the full JSON syntax and Permission Policy Actions and Resources for the complete catalog of supported actions and ARNs.

Example Permission Policy

This policy allows read-only access to a specific Gateway Group identified by its ID.

{
  "name": "ReadOnlyProdGatewayGroup",
  "desc": "Read-only access to the production gateway group.",
  "policy_document": {
    "statement": [
      {
        "effect": "allow",
        "resources": ["arn:api7:gateway:gatewaygroup/prod-group-id"],
        "actions": [
          "gateway:GetGatewayGroup",
          "gateway:GetGatewayInstance"
        ]
      }
    ]
  }
}

Permission Boundaries

Permission boundaries are policies attached directly to a user rather than through a role. They act as a "ceiling" for the user's permissions. Even if a role grants a specific action, the user cannot perform it unless the permission boundary also allows it.

Use boundaries to limit a user's operations to a specific scope, such as a single Gateway Group or environment, regardless of the roles they hold.

Permission Evaluation

API7 Gateway uses a policy-based evaluation engine to authorize requests.

1. The engine collects all policies from the user's assigned roles and their permission boundaries.
2. If any applicable policy has a deny effect, the request is immediately denied.
3. The request is only allowed if there is at least one allow policy that matches the action and resource.
4. If no policy explicitly allows the action, the request is denied by default.

Single Sign-On (SSO)

API7 Gateway supports external identity providers for authentication and user provisioning.

• OIDC (OpenID Connect): Integrate with providers like Okta, Auth0, or Google.
• SAML: Support for enterprise identity systems.
• LDAP: Authenticate users against an LDAP directory.
• SCIM: Automated user provisioning and de-provisioning from your identity provider.

Users authenticated through these methods will have their provider field set to sso or scim. For configuration details, see SSO Dashboard Settings.

Next Steps

• Role-Based Access Control
• Permission Policy Reference
• SSO Configuration Guide