Skip to main content
Version: 1.11.0

Typical Access Scenarios

This page walks through nine common ways to divide access in an organization with rule-based roles. Each scenario states the goal, defines the role in the dashboard and as an Admin API body, says who receives it, and describes what that person sees afterwards.

The scenarios share one example organization, so they can be set up side by side and compared. Rule-based roles are available in AISIX Enterprise and AISIX Cloud starting with control plane 1.11.0.

The Example Organization​

The scenarios assume the following setup:

  • Two environments, test and prod.
  • The tag keys dept, tier, and vendor, declared on the Tag Keys page. See Declare Tag Keys.
  • Two teams. payments has lead-payments as its lead and dev-alice as a member. search has dev-carol as a member.
  • Caller API keys in both environments: some assigned to individual members, some bound to a team with no member, and some tagged dept=payments or dept=search.
  • Models in both environments, some with the access tag tier=public and some with dept=payments or dept=search.
  • Provider keys with the access tag vendor=openai or vendor=anthropic.

API keys carry dept as a cost attribution tag. Models and provider keys carry their tags as Access tags in their create and edit forms.

Every person in the scenarios was invited with the default role, Restricted Member.

Create and Assign a Role​

In the dashboard:

  1. Open Roles and select New role.
  2. Enter the role's Name and add one rule card per row of the scenario's rule table.
  3. Select Create role.
  4. Assign the role from either the member's Roles panel on Members or the team's Team roles card.

Through the Admin API, send the scenario's body to POST /roles, then assign the role to a member by user_id or to a team by team_id. Replace TEST_ENV_ID in a body with the ID of the test environment.

# AISIX_CP includes /api and has no trailing slash.
# The local AISIX Enterprise quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

# Save the scenario's body as role.json first.
curl -sS -X POST "${AISIX_CP}/roles" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
-H "Content-Type: application/json" \
-d @role.json

# Assign the role to a member.
curl -sS -X POST "${AISIX_CP}/members/${USER_ID}/roles" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"role": "ROLE_NAME"}'

# Or give it to a team.
curl -sS -X POST "${AISIX_CP}/teams/${TEAM_ID}/roles" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"role": "ROLE_NAME"}'

Assigning roles takes an owner, or a member who holds role_assignments as in scenario 9. Defining roles takes a built-in admin or owner.

1. New Members Start Restricted​

Goal: a newly invited member has no access until someone decides what they need.

Role: the built-in Restricted Member. It reads only the API keys assigned to the member, to their teams, and to the teams they lead, and the usage of those keys. Nothing needs to be defined.

Who gets it: dev-new, through an invitation that keeps the preselected Restricted Member role.

What they see: Restricted Member cannot read any environment, so dev-new signs in to an empty environment switcher. It says they have no access to any environment yet and should contact an administrator, and links to My permissions, which lists the one Restricted Member rule. Pages of configuration are hidden, and so is Usage, which also needs environment read; Cost Analysis shows the usage of their keys across environments. Scenario 2 adds what it takes to browse their keys.

2. Regular Users See Only Their Own Keys, Models, and Usage​

Goal: a developer works with the API keys meant for them in every environment, and with the usage those keys produce, without seeing the keys of other members or the gateway configuration.

Role: Restricted Member already limits keys and usage to the member and their teams. The custom role environment-viewer adds the environment list, so the developer can open each environment in the dashboard:

Resource typesActionsEnvironmentsObjects
EnvironmentsReadnot applicableAll objects
{
"name": "environment-viewer",
"description": "Environment Viewer: read every environment",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
}
]
}

Who gets it: dev-alice, who keeps Restricted Member and also receives environment-viewer.

What they see:

  • Both test and prod appear in the environment switcher.
  • API keys lists the keys assigned to Alice and the keys bound to the payments team with no member. A teammate's personal key, even one bound to payments, and every key of search are absent, and the Admin API answers 404 for them.
  • Logs, Usage, and Cost Analysis show only the requests of those keys.
  • The models her keys can call appear on each key by name, with a lock: Alice can see which models a key may use, but cannot open their configuration. The Models page and every other configuration page are hidden.
  • Creating, editing, and rotating keys is disabled, and hovering over the action names the missing permission.

3. Self-Service Developers Manage Their Own Keys​

Goal: a developer creates, rotates, and deletes their own keys in the test environment, can choose only from approved models, and has no access to production.

Role: the custom role self-service-developer:

Resource typesActionsEnvironmentsObjects
EnvironmentsReadnot applicableSpecific objects: test
API keysAll actionsSpecific environments: testBy assignment: me
UsageReadSpecific environments: testBy assignment: me
ModelsReadSpecific environments: testBy tag: tier=public
{
"name": "self-service-developer",
"description": "Self-service Developer: own keys and public models in test",
"rules": [
{
"resources": ["environments"],
"actions": ["read"],
"selector": {"ids": ["TEST_ENV_ID"]}
},
{
"resources": ["api_keys"],
"actions": ["read", "create", "update", "delete"],
"environments": {"ids": ["TEST_ENV_ID"]},
"selector": {"assigned_to": ["self"]}
},
{
"resources": ["usage"],
"actions": ["read"],
"environments": {"ids": ["TEST_ENV_ID"]},
"selector": {"assigned_to": ["self"]}
},
{
"resources": ["models"],
"actions": ["read"],
"environments": {"ids": ["TEST_ENV_ID"]},
"selector": {"tags": {"tier": "public"}}
}
]
}

Who gets it: dev-bob, as a direct assignment.

What they see:

  • Only test appears in the environment switcher. prod is not listed, and its pages are refused.
  • API keys lists Bob's own keys. He can create keys, but each new key must name him as its member, or the request is refused with 400. He can rotate, edit, and delete his keys, but cannot hand one to someone else, because a key must stay assigned to him after an edit.
  • The model picker of a key offers only the models tagged tier=public, and Models lists only those. Turning on All models for a key is refused, because that needs read on every model in the environment.
  • Logs and Usage show only his keys' requests.

4. Team Leads Manage Their Team's Keys​

Goal: a team lead manages every API key of the teams they lead, in every environment, and sees the usage of those keys and the team's models.

Role: the custom role team-lead, held together with Restricted Member:

Resource typesActionsEnvironmentsObjects
EnvironmentsReadnot applicableAll objects
API keysAll actionsAll environmentsBy assignment: teams I lead
UsageReadAll environmentsBy assignment: teams I lead
ModelsReadAll environmentsBy tag: dept=payments
{
"name": "team-lead",
"description": "Team Lead: every key of the teams I lead",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
},
{
"resources": ["api_keys"],
"actions": ["read", "create", "update", "delete"],
"environments": "all",
"selector": {"assigned_to": ["led_teams"]}
},
{
"resources": ["usage"],
"actions": ["read"],
"environments": "all",
"selector": {"assigned_to": ["led_teams"]}
},
{
"resources": ["models"],
"actions": ["read"],
"environments": "all",
"selector": {"tags": {"dept": "payments"}}
}
]
}

Who gets it: lead-payments, the lead of payments, as a direct assignment.

What they see:

  • API keys lists every key bound to payments in both environments, including the personal keys of team members that are bound to the team, and their own keys through Restricted Member.
  • They can create keys bound to payments, and rotate, edit, disable, or delete the team's keys. A key cannot be moved out of the team. Naming another member as a new key's member also needs read on members, so the lead binds new keys to the team, or to the team and themselves.
  • Logs and Usage show the requests of every payments key, and Models lists the models tagged dept=payments.
  • The rule follows the roster: if they stop leading payments, the team's keys drop out of their view.

5. Isolate Departments That Share Environments​

Goal: two departments work in the same test and prod environments, and each sees only its own keys, usage, and models.

Role: the custom role search-department, given to the department's team:

Resource typesActionsEnvironmentsObjects
EnvironmentsReadnot applicableAll objects
API keys, UsageReadAll environmentsBy tag: dept=search
ModelsReadAll environmentsBy tag: dept=search
{
"name": "search-department",
"description": "Search Department: objects tagged dept=search",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
},
{
"resources": ["api_keys", "usage"],
"actions": ["read"],
"environments": "all",
"selector": {"tags": {"dept": "search"}}
},
{
"resources": ["models"],
"actions": ["read"],
"environments": "all",
"selector": {"tags": {"dept": "search"}}
}
]
}

Who gets it: the search team, in its Team roles card. dev-carol receives it as a member of search, and so does anyone added to the team later. A payments-department role with dept=payments, given to payments, completes the split.

What they see:

  • API keys in both environments lists the keys tagged dept=search, whoever owns them.
  • Logs, Usage, and Cost Analysis show the requests of those keys, and Models lists the models tagged dept=search.
  • Nothing tagged dept=payments appears anywhere: not its keys, its usage, or its models, and the Admin API answers 404 for them.
  • My permissions shows the rules with the source search-department via team search.

The department boundary is the tag, so tag every key and model a department owns, and declare who may change the tags. A key's dept tag also drives cost attribution, so the same tag splits both access and cost.

6. Delegate One Environment​

Goal: an operator administers everything inside the test environment without seeing prod or organization settings.

Role: the custom role test-environment-admin. In the dashboard, select every type under Environment resources at once; the selection is saved as the list of types that exist at that moment:

Resource typesActionsEnvironmentsObjects
EnvironmentsReadnot applicableSpecific objects: test
Every environment resourceAll actionsSpecific environments: testAll objects
Provider keysReadnot applicableAll objects
{
"name": "test-environment-admin",
"description": "Test Environment Admin: everything inside test",
"rules": [
{
"resources": ["environments"],
"actions": ["read"],
"selector": {"ids": ["TEST_ENV_ID"]}
},
{
"resources": [
"models", "api_keys", "usage", "guardrails", "cache_policies",
"rate_limits", "observability_exporters", "passthrough_routes",
"oidc_providers", "claim_mappings", "mcp_policy",
"gateway_certificates", "dp_nodes", "playground"
],
"actions": ["read", "create", "update", "delete"],
"environments": {"ids": ["TEST_ENV_ID"]}
},
{
"resources": ["provider_keys"],
"actions": ["read"]
}
]
}

The provider key rule is needed because an environment admin must be able to read the provider keys it builds models on: a model can point only at a provider key its creator can read.

Who gets it: ops-dan, as a direct assignment.

What they see:

  • Only test appears in the environment switcher, and everything inside it can be configured: models, keys, guardrails, policies, gateway certificates and data planes, the playground, and its usage.
  • prod is invisible, and the environment itself cannot be renamed or deleted, which takes update and delete on environments.
  • Provider keys is readable but not editable. Other organization pages, such as Teams, Members, and Budgets, are hidden.

A role on environment resources reaches organization resources only through references, which is why the role reads provider keys. To limit Dan to some vendors, narrow that rule by tag. Likewise, a new key can name only Dan himself or his own teams unless the role also reads members and teams.

7. Finance Reviews Usage and Cost​

Goal: a finance reviewer sees organization-wide usage, cost, budgets, and pricing, without access to any configuration.

Role: the custom role finance-viewer:

Resource typesActionsEnvironmentsObjects
EnvironmentsReadnot applicableAll objects
UsageReadAll environmentsAll objects
Budgets, Model pricingReadnot applicableAll objects
{
"name": "finance-viewer",
"description": "Finance Viewer: all usage, budgets, and pricing",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
},
{
"resources": ["usage"],
"actions": ["read"],
"environments": "all"
},
{
"resources": ["budgets", "model_pricing"],
"actions": ["read"]
}
]
}

Who gets it: finance-eve, as a direct assignment.

What they see:

  • Usage and Cost Analysis cover every environment, including the Target model view and the budget figures on team and tag groups, because Eve reads all usage without an object scope and reads budgets.
  • Logs in each environment shows every request with every field.
  • Budgets and Model pricing are readable but not editable.
  • API keys, members, and models appear by name with a lock wherever usage references them. Eve cannot open them, and their configuration pages are hidden.

8. Manage One Vendor's Provider Keys​

Goal: a vendor contact maintains the OpenAI provider keys without seeing any other provider key.

Role: the custom role openai-key-manager:

Resource typesActionsEnvironmentsObjects
Provider keysRead, Updatenot applicableBy tag: vendor=openai
{
"name": "openai-key-manager",
"description": "OpenAI Key Manager: provider keys tagged vendor=openai",
"rules": [
{
"resources": ["provider_keys"],
"actions": ["read", "update"],
"selector": {"tags": {"vendor": "openai"}}
}
]
}

Who gets it: vendor-frank, as a direct assignment.

What they see:

  • Provider keys lists only the keys tagged vendor=openai, and Frank can edit them. A key tagged vendor=anthropic is absent, and the Admin API answers 404 for it.
  • An edit that removes or changes the vendor=openai tag is refused, because the key must stay in scope after the change. He cannot create or delete provider keys.
  • He reads no environment, so the environment switcher is empty.

9. Delegate Role Assignment​

Goal: an access manager assigns roles to members and teams and maintains team rosters, without being an owner.

Role: the custom role access-manager:

Resource typesActionsEnvironmentsObjects
Role assignmentsCreate, Deletenot applicableAll objects
Members, RolesReadnot applicableAll objects
TeamsRead, Updatenot applicableAll objects
{
"name": "access-manager",
"description": "Access Manager: assigns roles and maintains team rosters",
"rules": [
{
"resources": ["role_assignments"],
"actions": ["create", "delete"]
},
{
"resources": ["members", "roles"],
"actions": ["read"]
},
{
"resources": ["teams"],
"actions": ["read", "update"]
}
]
}

While you define it, the rule on teams shows a warning: updating teams includes changing their members, so the holder can hand the teams' roles to anyone.

Who gets it: it-grace, as a direct assignment.

What they see:

  • On Members, Grace can add and remove every member's manual roles and see each member's Effective permissions. The Owner role is not offered, and roles assigned by SSO or SCIM stay locked.
  • On Teams, she can add and remove team members and, in Team roles, the team's roles.
  • On Roles, she can read every role and remove holders on the Holders tab, but cannot create or edit roles: defining roles is reserved for the built-in owner and admin.
  • She cannot invite or remove members.

Assigning roles is equivalent to admin. Grace can give any role except Owner, Admin included, to anyone, herself included. Give this role only to people you would trust with admin. See Who Can Change Access.

Next Steps​

See Roles and Permissions for the full rule model and resource types, and Budgets for caps that hold when members can create their own keys.