> This page is for Multi-Tenant, version v3.0 (default).
> For other versions, use one of these documentation indexes:
> - v3.0 (default): https://docs.nvidia.com/run-ai/multi-tenant/v3.0/llms.txt
> - v2.26: https://docs.nvidia.com/run-ai/multi-tenant/v2.26/llms.txt
> - v2.25: https://docs.nvidia.com/run-ai/multi-tenant/v2.25/llms.txt
> - v2.24: https://docs.nvidia.com/run-ai/multi-tenant/v2.24/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server.

# Access Rules

Access rules provide users, groups, or service accounts privileges to system entities. An access rule is the assignment of a role to a subject in a scope: `<Subject>` is a `<Role>` in a `<Scope>`.

## Scope Behavior

When creating an access rule, the `scopeType` and associated scope identifier, `scopeId`, determine where the access rule is available and who can use it in a multi-tenant environment:

* `scopeType = system` - Creates a global access rule that applies that is available across all customer tenants.
* `scopeType = tenant` + customer tenant ID - Creates an access rule that applies only within that customer tenant using `scopeId`.
* `scopeType = tenant` + Console/system tenant ID - Creates an access rule scoped to the platform owner (host organization) tenant using `scopeId`.

## Privileged Escalation Enforcement

When creating access rules across tenants, apply the principle of no privilege escalation:

* A user can assign roles only within the limits of their own permissions.
* Assigning a role that grants broader permissions than the caller is blocked or restricted by the platform.

## Create an Access Rule

To create an access rule:

* Send a `POST` request to the `/api/v1/authorization/access-rules` endpoint. See [Access rules](https://docs.nvidia.com/run-ai/multi-tenant/v3.0/reference/rest-api/endpoints/authentication-and-authorization/access-rules/create-access-rule) API for more details.
* Provide the following:
  * The **subject** you want to assign a role to:
    * `subjectType`: `user`, `group`, or `service-account`
    * `subjectId`: the unique identifier for that subject (for example, a user email or group name)
  * The **role ID** you want to assign (`roleId`). See Roles API to retrieve a list of roles.
  * The **scope** where the access rule applies:
    * `scopeType`: `system` or `tenant`
    * `scopeId`: the identifier of the system tenant or customer tenant

Example: Assign a role at **system scope** (global context):

```bash
curl -L 'https://<COMPANY-URL>/api/v1/authorization/access-rules' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
    "subjectId": "platform-admin@company.com",
    "subjectType": "user",
    "roleId": 56,
    "scopeType": "system",
    "scopeId": "<SYSTEM_ID>"
  }'
```

Example: Assign a role within a specific **customer tenant**:

```bash
curl -L 'https://<COMPANY-URL>/api/v1/authorization/access-rules' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
    "subjectId": "user@company.com",
    "subjectType": "user",
    "roleId": 12,
    "scopeType": "tenant",
    "scopeId": "<CUSTOMER-TENANT-ID>"
  }'
```

Example: Assign a role within the **console/system tenant**:

```bash
curl -L 'https://<COMPANY-URL>/api/v1/authorization/access-rules' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
    "subjectId": "operator@company.com",
    "subjectType": "user",
    "roleId": 34,
    "scopeType": "tenant",
    "scopeId": "<CONSOLE-SYSTEM-TENANT-ID>"
  }'
```