# 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://run-ai-docs.nvidia.com/multi-tenant-api/2.24/authentication-and-authorization/access-rules) 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>"
  }'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://run-ai-docs.nvidia.com/multi-tenant/2.24/infrastructure-setup/authentication-and-authorization/access-rules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.