> This page is for version Latest (default).
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.8.0: https://docs.nvidia.com/nemo-helix/v0.8.0/llms.txt
> - 0.7.1: https://docs.nvidia.com/nemo-helix/v0.7.1/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo-helix/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo-helix/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo-helix/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo-helix/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo-helix/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo-helix/v0.3.0/llms.txt
> - 0.2.0: https://docs.nvidia.com/nemo-helix/v0.2.0/llms.txt

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

# API Scopes

API scopes are token-level access restrictions that sit on top of role-based permissions. They control which parts of the API a bearer token can access, independent of the user's role.

For role-based permissions, see [Roles & Permissions](/documentation/access-control/authorization/roles-and-permissions). For the RBAC model, see [Authorization Concepts](/documentation/access-control/concepts).

## How Scopes Work

NeMo Helix API scopes are values in a token's `scope` or `scp` claim. They can come from the configured IdP during OIDC login, or from NeMo-issued scoped tokens such as Scoped Access Keys and workload access tokens. They follow the format `resource-group:access-type`. Each API endpoint is associated with one or more required scopes.

When a request arrives, the PDP checks:

1. Does the token have at least one of the endpoint's required scopes?
2. Does the principal have the required role permissions in the workspace?

Both must pass. This is the **two-layer authorization** model.

## Scopes Are Not Groups

OIDC tokens can carry both identity claims and OAuth scopes. NeMo Helix treats them differently:

* **Identity claims** identify the caller. The configured `groups_claim` becomes NeMo Helix group principals that can receive workspace role bindings, for example `employee.profile.read`.
* **OAuth scopes** come from a token's `scope` or `scp` claim. They are not group principals and never grant roles.
* **NeMo API scopes** are OAuth scope values with NeMo Helix API-scope syntax, such as `platform:read` and `models:write`. NeMo Helix uses them to narrow which APIs the token can call.

External IdP scopes such as `openid`, `profile`, `email`, `employee.profile.read`, and provider URL or URN scopes do not grant roles and do not need to be filtered out of the token. Dotted identity values are safe as group names when they arrive in the configured `groups_claim`; they are not groups when they arrive in `scope` or `scp`.

## OIDC Login Scopes

`nemo auth login` requests OAuth scopes from the configured IdP. Those requested scopes can include:

* OIDC protocol scopes, such as `openid`, `profile`, `email`, and `offline_access`
* NeMo Helix API scope names that the IdP application knows about, such as `platform:read` and `platform:write`

Some IdPs require API scopes to be sent in a resource-qualified form. When auth discovery includes a scope prefix, the CLI output shows both the NeMo Helix scope name and the OAuth scope sent to the IdP, for example `platform:read (api://<app-client-id>/platform:read)`. Users should request the short NeMo Helix scope name; the CLI applies the discovered prefix automatically.

OIDC login scopes are not group principals and do not create role bindings. If the IdP sends group or entitlement values that should grant workspace access, put those values in the configured identity claim, such as `groups_claim`, and bind roles to those principals.

## Available Scopes

### Per-API Scopes

Each API has a read and write scope. A token with an API-specific scope can only access that API's endpoints.

| API              | Read Scope              | Write Scope              | Endpoints                               |
| ---------------- | ----------------------- | ------------------------ | --------------------------------------- |
| Audit            | `audit:read`            | `audit:write`            | `/apis/garak/`                          |
| Auth             | `auth:read`             | `auth:write`             | `/apis/auth/`                           |
| Data Designer    | `data-designer:read`    | `data-designer:write`    | `/apis/data-designer/`                  |
| Entities         | `entities:read`         | `entities:write`         | `/apis/entities/` (internal — see note) |
| Files            | `files:read`            | `files:write`            | `/apis/files/`                          |
| Guardrails       | `guardrails:read`       | `guardrails:write`       | `/apis/guardrails/`                     |
| Inference        | `inference:read`        | `inference:write`        | `/apis/inference-gateway/`              |
| Jobs             | `jobs:read`             | `jobs:write`             | `/apis/jobs/`                           |
| Models           | `models:read`           | `models:write`           | `/apis/models/`                         |
| Safe Synthesizer | `safe-synthesizer:read` | `safe-synthesizer:write` | `/apis/safe-synthesizer/`               |
| Secrets          | `secrets:read`          | `secrets:write`          | `/apis/secrets/`                        |

> **Note**
>
> The `entities:read` and `entities:write` scopes are for internal service-to-service usage. The generic entities API is not accessible to regular users — only HelixAdmin and service principals can access it. Users interact with entities through feature-specific APIs (Models, Evaluation, etc.) which use their own scopes.

### Platform Scopes

The `platform:*` scopes act as catch-alls that grant access to **all** APIs:

| Scope            | Description                       |
| ---------------- | --------------------------------- |
| `platform:read`  | Read access to all platform APIs  |
| `platform:write` | Write access to all platform APIs |

Each endpoint in the authorization policy lists both its API-specific scope and the corresponding `platform:*` scope. A token needs at least one of the listed scopes to pass the scope check.

### Requesting Scopes

For an interactive OIDC login, use `nemo auth login --scope` to request a narrower NeMo Helix API scope set from the configured IdP:

```bash
# Full access, using the deployment's configured default_scopes
nemo auth login

# Read-only access to all APIs
nemo auth login --scope "platform:read"

# Access only selected APIs
nemo auth login --scope "files:read files:write models:read models:write"
```

The CLI keeps the deployment's non-API OIDC defaults, such as `openid`, `profile`, `email`, and `offline_access`, and applies the discovered `scope_prefix` when the IdP requires resource-qualified API scopes.

For automation tokens, use Scoped Access Keys when the token should be narrower than the caller's normal OIDC session. Access-key `--scope` values are service areas; NeMo Helix expands each area into the corresponding read and write API scopes:

```bash
nemo auth access-keys create --name "intake-worker" \
  --scope intake,entities \
  --workspace ml-team:Editor
```

## Two-Layer Authorization

For a request to succeed, it must satisfy **both** requirements:

1. **Token scope check**: The API token must have at least one of the endpoint's required scopes
2. **Permission check**: The principal must have the required permissions through role grants in the workspace

### Examples

| User Role | Token Scopes                   | Request      | Result                  |
| --------- | ------------------------------ | ------------ | ----------------------- |
| Editor    | `platform:read platform:write` | Create model | ✓ Allowed               |
| Editor    | `platform:read` only           | Create model | ✗ Denied by scope check |
| Viewer    | `platform:read platform:write` | Create model | ✗ Denied by role check  |
| Viewer    | `platform:read`                | List models  | ✓ Allowed               |

This enables least-privilege tokens: a caller can use a token whose API scope is narrower than the caller's role grants.

## IdP Configuration

Configure your IdP application with the OAuth scopes your login flow requests. At minimum this is usually `openid`, `profile`, `email`, and `offline_access`. If your deployment requests NeMo Helix API scope names during login, define those scopes on the same IdP application according to your provider's normal API-scope or consent model.

## Scope Checking Behavior

The PDP distinguishes between external OAuth scopes and NeMo Helix API-scope syntax:

* **No scopes in token**: scope checking is skipped (backward compatible)
* **Only non-API OAuth scopes** (`openid`, `profile`, `email`, dotted scopes, provider URL scopes, or provider URNs): treated as no NeMo API scopes, so scope checking is skipped
* **NeMo API scopes present** (`area:action`): at least one required scope for the endpoint must match
* **HelixAdmin**: still obeys token scope restrictions when the token contains NeMo API scopes, so a scoped-down token stays scoped down

## When to Restrict Scoped Tokens

* **CI/CD tokens**: restrict to only the service areas the pipeline needs
* **Monitoring scripts**: prefer read-only NeMo API scopes when the token issuer supports per-action scopes
* **Data ingestion scripts**: restrict to data intake and storage service areas
* **Model catalog readers**: prefer model read scopes when the token issuer supports per-action scopes
* **Shared service accounts**: limit blast radius by restricting to only the areas needed

## Related

* [Roles & Permissions](/documentation/access-control/authorization/roles-and-permissions) — Role-based permission model.
* [Using Authentication](/documentation/access-control/authentication/using-authentication) — Log in, create Scoped Access Keys, and manage tokens.
* [OIDC Setup](/documentation/access-control/authentication/oidc-setup) — Configure OIDC login scopes and claim mapping.
* [Security Model](/documentation/access-control/security-model) — Trust boundaries and two-layer authorization.