# Typical Access Scenarios

This page walks through nine common ways to divide access in an organization with [rule-based roles](https://docs.api7.ai/ai-gateway/cloud/custom-roles.md). 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-example-organization "Direct link to 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](https://docs.api7.ai/ai-gateway/cloud/cost-attribution-tags.md#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](https://docs.api7.ai/ai-gateway/cloud/cost-attribution-tags.md#set-tags-on-api-keys-teams-and-members). 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[​](#create-and-assign-a-role "Direct link to 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](#9-delegate-role-assignment). Defining roles takes a built-in admin or owner.

## 1. New Members Start Restricted[​](#1-new-members-start-restricted "Direct link to 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[​](#2-regular-users-see-only-their-own-keys-models-and-usage "Direct link to 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 types | Actions | Environments   | Objects     |
| -------------- | ------- | -------------- | ----------- |
| Environments   | Read    | not applicable | All 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[​](#3-self-service-developers-manage-their-own-keys "Direct link to 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 types | Actions     | Environments                  | Objects                  |
| -------------- | ----------- | ----------------------------- | ------------------------ |
| Environments   | Read        | not applicable                | Specific objects: `test` |
| API keys       | All actions | Specific environments: `test` | By assignment: me        |
| Usage          | Read        | Specific environments: `test` | By assignment: me        |
| Models         | Read        | Specific environments: `test` | By 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[​](#4-team-leads-manage-their-teams-keys "Direct link to 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 types | Actions     | Environments     | Objects                     |
| -------------- | ----------- | ---------------- | --------------------------- |
| Environments   | Read        | not applicable   | All objects                 |
| API keys       | All actions | All environments | By assignment: teams I lead |
| Usage          | Read        | All environments | By assignment: teams I lead |
| Models         | Read        | All environments | By 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[​](#5-isolate-departments-that-share-environments "Direct link to 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 types  | Actions | Environments     | Objects               |
| --------------- | ------- | ---------------- | --------------------- |
| Environments    | Read    | not applicable   | All objects           |
| API keys, Usage | Read    | All environments | By tag: `dept=search` |
| Models          | Read    | All environments | By 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](https://docs.api7.ai/ai-gateway/cloud/cost-attribution-tags.md), so the same tag splits both access and cost.

## 6. Delegate One Environment[​](#6-delegate-one-environment "Direct link to 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 types             | Actions     | Environments                  | Objects                  |
| -------------------------- | ----------- | ----------------------------- | ------------------------ |
| Environments               | Read        | not applicable                | Specific objects: `test` |
| Every environment resource | All actions | Specific environments: `test` | All objects              |
| Provider keys              | Read        | not applicable                | All 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[​](#7-finance-reviews-usage-and-cost "Direct link to 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 types         | Actions | Environments     | Objects     |
| ---------------------- | ------- | ---------------- | ----------- |
| Environments           | Read    | not applicable   | All objects |
| Usage                  | Read    | All environments | All objects |
| Budgets, Model pricing | Read    | not applicable   | All 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[​](#8-manage-one-vendors-provider-keys "Direct link to 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 types | Actions      | Environments   | Objects                 |
| -------------- | ------------ | -------------- | ----------------------- |
| Provider keys  | Read, Update | not applicable | By 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[​](#9-delegate-role-assignment "Direct link to 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 types   | Actions        | Environments   | Objects     |
| ---------------- | -------------- | -------------- | ----------- |
| Role assignments | Create, Delete | not applicable | All objects |
| Members, Roles   | Read           | not applicable | All objects |
| Teams            | Read, Update   | not applicable | All 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](https://docs.api7.ai/ai-gateway/cloud/custom-roles.md#who-can-change-access).

## Next Steps[​](#next-steps "Direct link to Next Steps")

See [Roles and Permissions](https://docs.api7.ai/ai-gateway/cloud/custom-roles.md) for the full rule model and resource types, and [Budgets](https://docs.api7.ai/ai-gateway/traffic-controls/budgets.md) for caps that hold when members can create their own keys.
