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. For the RBAC model, see Authorization 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:

Does the token have at least one of the endpoint’s required scopes?
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.

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/auditor/`
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/`

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:

# 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:

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:

Token scope check: The API token must have at least one of the endpoint’s required scopes
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

Roles & Permissions — Role-based permission model.
Using Authentication — Log in, create Scoped Access Keys, and manage tokens.
OIDC Setup — Configure OIDC login scopes and claim mapping.
Security Model — Trust boundaries and two-layer authorization.