NVIDIA-NeMo · ironcommit · Sep 1, 2026 · coderabbitai · Sep 1, 2026
@@ -26,7 +26,8 @@ Once your IdP is connected, see [Using Authentication](/documentation/access-con
 |--------|-----------------|----------|
 | **Device flow** (browser) | `nemo auth login` | Interactive use — opens browser to sign in with your IdP |
 | **Password grant** | `nemo auth login --username <user> --password <pass>` | CI/CD pipelines — non-interactive |
-| **Direct from IdP** | Use your IdP's token endpoint or workload identity | Custom integrations, service accounts |
+| **Scoped Access Key** | `nemo auth access-keys create` | Non-SDK automation, including NeMo service accounts |
+| **Direct from IdP** | Use your IdP's token endpoint or workload identity | Custom integrations that require IdP-issued scopes |
 
 The CLI stores the token and auto-refreshes it before expiry. The SDK reads the stored token from the CLI config automatically — after `nemo auth login`, `NeMoPlatform()` works with no arguments.
 

@@ -63,7 +63,7 @@ For CI pipelines, use the password grant to obtain a token without a browser: `n
 
 <Warning>
 
-Password grant sends credentials directly to the IdP and **bypasses MFA**. Many production IdPs disable it. Use a dedicated service account with minimal scopes where possible.
+Password grant sends credentials directly to the IdP and **bypasses MFA**. Many production IdPs disable it. Use a dedicated IdP automation identity with minimal scopes where possible.
 
 </Warning>
 ## Make API Calls
@@ -107,8 +107,8 @@ curl -H "Authorization: Bearer $TOKEN" \
 ## Scoped Access Keys for Non-SDK Clients
 
 When Scoped Access Keys are enabled by the platform administrator, an
-authenticated user can mint a scoped bearer token for automation that cannot use
-the SDK's OIDC refresh flow:
+authenticated user can mint a lifecycle-managed bearer token for automation that
+cannot use the SDK's OIDC refresh flow:
 
 ```bash
 # Create a Scoped Access Key with the platform default expiry and print the token once.
@@ -119,6 +119,31 @@ Scoped Access Key management commands live under the `auth` namespace as
 `nemo auth access-keys ...`. The `access-keys` command group is not a top-level CLI
 command and is not a separate NeMo Platform plugin.
 
+By default, `create` makes a user-bound key for the signed-in user's effective
+principal. A human PlatformAdmin can instead create a service-account-bound key:
+
+```bash
+nemo auth access-keys create \
+  --service-account intake-otel-writer \
+  --name intake-otel-write \
+  --expires-in 604800
+```
+
+The service account does not need to exist in the IdP and does not run
+`nemo auth login`. NeMo stamps the token subject as
+`service-account:intake-otel-writer`; grant workspace access to that prefixed
+principal with `nemo workspaces members ...`.
+
+<Note>
+
+The current access-key create CLI supports `--service-account` and
+`--expires-in`, but it does not expose per-key API scope selection. For
+service-account access keys, use workspace role bindings and short lifetimes to
+limit access. API-scope checks still apply to bearer tokens that contain
+`scope` or `scp` claims, such as OIDC access tokens.
+
+</Note>
+
 `create` prints the Scoped Access Key token once. Store it in your secret
 manager and send it in the standard `Authorization` header:
 
@@ -127,8 +152,10 @@ curl -H "Authorization: Bearer $NMP_SCOPED_ACCESS_KEY" \
  https://nmp.company.com/apis/entities/v2/workspaces
 ```
 
-Scoped Access Keys are signed JWT bearer tokens scoped to the principal and
-groups present when the key is created. By default, new keys use the platform's
+Scoped Access Keys are signed JWT bearer tokens scoped to a principal identity.
+User-bound keys preserve the user's principal and groups at creation time.
+Service-account-bound keys use a non-human `service-account:<id>` principal and
+do not carry user email or group claims. By default, new keys use the platform's
 configured default expiry, which is 30 days unless the administrator changes it.
 Pass `--expires-in <seconds>` to request a specific finite lifetime. Pass
 `--expires-in none` only for deployments where the administrator has explicitly
@@ -144,13 +171,16 @@ nemo auth access-keys unsuspend ak_0123456789abcdef0123456789abcdef
 nemo auth access-keys revoke ak_0123456789abcdef0123456789abcdef
 ```
 
-The list includes each key's `ACTIVE`, `EXPIRED`, `SUSPENDED`, or `REVOKED` status
-plus its description, issuer, audiences, creation time, and expiration time. Suspension
-and revocation take effect on subsequent authenticated platform requests. Use suspension
-to temporarily block a key, such as while investigating suspected misuse, without
-permanently revoking it. An unexpired suspended key can be restored with `unsuspend`. If
-the key expires while suspended, `unsuspend` is a no-op and reports `EXPIRED`. A revoked
-key cannot be restored. Rotation is not implemented.
+The list includes each key's `ACTIVE`, `EXPIRED`, `SUSPENDED`, or `REVOKED`
+status plus its entity type, principal, description, issuer, audiences, creation
+time, and expiration time. Regular users see their own user-bound keys.
+PlatformAdmins also see all service-account-bound keys, including keys created
+by other admins. Suspension and revocation take effect on subsequent
+authenticated platform requests. Use suspension to temporarily block a key, such
+as while investigating suspected misuse, without permanently revoking it. An
+unexpired suspended key can be restored with `unsuspend`. If the key expires
+while suspended, `unsuspend` is a no-op and reports `EXPIRED`. A revoked key
+cannot be restored. Rotation is not implemented.
 
 ### Token Inspection
 
@@ -166,14 +196,18 @@ Decode the token to inspect claims:
 nemo auth token --decode
 ```
 
-Key claims to check:
+Key claims to check on OIDC tokens:
 
 - `email` or `upn` — the principal identity
 - `scp` or `scope` — granted scopes
 - `exp` — expiry timestamp
 - `iss` — issuer URL (must match your config)
 - `aud` — audience (must match your config)
 
+For Scoped Access Keys, check `sub`, `jti`, `nmp_token_type`, and
+`nmp_access_key`. Service-account keys have `sub: service-account:<id>` and
+`nmp_access_key.entity_type: SERVICE_ACCOUNT`.
+
 ## Token Management
 
 ### How Auto-Refresh Works
@@ -226,5 +260,6 @@ The OIDC token endpoint is **not** stored — it is discovered at runtime from y
 
 - [OIDC](/documentation/access-control/authentication/oidc-setup) — Configure your identity provider.
 - [API Scopes](/documentation/access-control/authorization/api-scopes) — Scope model and available scopes.
+- [Scoped Intake Tokens](/documentation/access-control/deployment/scoped-intake-tokens) — Create service-account access keys for Intake.
 - [Security Model](/documentation/access-control/security-model) — Trust boundaries and the principal model.
 - [Troubleshooting](/documentation/access-control/troubleshooting) — Fix common 401/403 errors and login failures.
@@ -5,20 +5,29 @@
 title: "API Scopes"
 description: ""
 ---
-API scopes are token-level access restrictions that sit on top of role-based permissions. They control which parts of the API a token can access, independent of the user's role.
+API scopes are token-level access restrictions that sit on top of role-based
+permissions. When a token carries platform API scopes, those scopes control
+which parts of the API the token can access, independent of the token
+principal'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
 
-Scopes are included in OIDC tokens and follow the format `resource-group:access-type`. Each API endpoint is associated with one or more required scopes.
+Scopes are read from bearer-token `scope` or `scp` claims and follow the format
+`resource-group:access-type`. OIDC access tokens commonly carry these claims.
+Scoped Access Key validation also honors scope claims when they are present, but
+the current access-key create CLI/API does not expose per-key API scope
+selection. Each API endpoint is associated with one or more required scopes.
 
-When a request arrives, the PDP checks:
+When a request arrives with platform API scopes, 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.
+Both must pass when platform API scopes are present. Tokens with no scope claim,
+or only standard OIDC scopes, skip the scope check for compatibility and rely on
+the role-permission check.
 
 ## Available Scopes
 
@@ -35,6 +44,7 @@ Each API has a read and write scope. A token with an API-specific scope can only
 | Files | `files:read` | `files:write` | `/apis/files/` |
 | Guardrails | `guardrails:read` | `guardrails:write` | `/apis/guardrails/` |
 | Inference | `inference:read` | `inference:write` | `/apis/inference-gateway/` |
+| Intake | `intake:read` | `intake:write` | `/apis/intake/` |
 | 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/` |
@@ -54,7 +64,9 @@ The `platform:*` scopes act as catch-alls that grant access to **all** APIs:
 | `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.
+Each endpoint in the authorization policy lists both its API-specific scope and
+the corresponding `platform:*` scope. When a token provides platform API scopes,
+it needs at least one of the listed scopes to pass the scope check.
 
 ### Requesting Scopes
 
@@ -73,7 +85,8 @@ nemo auth login --scope "files:read files:write models:read models:write"
 
 ## Two-Layer Authorization
 
-For a request to succeed, it must satisfy **both** requirements:
+When a token provides platform API scopes, a request 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
@@ -87,11 +100,15 @@ For a request to succeed, it must satisfy **both** requirements:
 | Viewer | `platform:read platform:write` | Create model | ✗ Denied by role check |
 | Viewer | `platform:read` | List models | ✓ Allowed |
 
-This enables least-privilege tokens: an Editor can create a read-only token (`platform:read`) for monitoring scripts that should never modify resources.
+This enables least-privilege OIDC tokens: an Editor can sign in with
+`platform:read` for monitoring scripts that should never modify resources.
 
 ## IdP Configuration
 
-Scopes must be registered in your IdP as custom API scopes. The CLI requests them during the OAuth flow, and the IdP includes granted scopes in the access token.
+For OIDC tokens, scopes must be registered in your IdP as custom API scopes. The
+CLI requests them during the OAuth flow, and the IdP includes granted scopes in
+the access token. For NeMo service-account access keys, see
+[Scoped Intake Tokens](/documentation/access-control/deployment/scoped-intake-tokens).
 
 If your IdP prefixes scopes (e.g., Azure AD uses `api://client-id/platform:read`), configure `scope_prefix` in the NeMo Platform OIDC settings so the platform strips the prefix before authorization:
 
@@ -114,11 +131,14 @@ The PDP distinguishes between OIDC standard scopes and platform scopes:
 
 ## When to Restrict Scopes
 
-- **CI/CD tokens** that should only read: `platform:read`
-- **Monitoring scripts** that should never modify resources: `platform:read`
-- **Data ingestion scripts**: `files:read files:write`
+- **OIDC CI/CD tokens** that should only read: `platform:read`
+- **OIDC monitoring tokens** that should never modify resources: `platform:read`
+- **OIDC data ingestion tokens**: `intake:write`
+- **Service-account Intake keys**: grant the `service-account:<id>` principal the
+  minimum workspace role, such as Viewer for readers or Editor for OTLP writers
 - **Model catalog readers**: `models:read`
-- **Shared service accounts**: limit blast radius by restricting to only the areas needed
+- **Shared IdP automation identities**: limit blast radius by requesting only the
+  scopes needed by that integration
 
 ## Related
 

@@ -5,20 +5,24 @@
 title: "Authorization"
 description: ""
 ---
-NeMo Platform authorization controls what authenticated users can do. Every API request is evaluated against the user's token scopes and role bindings before it is allowed.
+NeMo Platform authorization controls what authenticated principals can do. Every
+API request is evaluated against the principal's role bindings, and against
+token scopes when the token carries platform API scopes.
 
 The authorization model has four building blocks:
 
 1. **Workspaces** — the authorization boundary. All resources belong to a workspace.
 2. **Roles** — permission bundles (Viewer, Editor, Admin) granted per workspace.
-3. **Role bindings** — the link between a user, a role, and a workspace.
-4. **Scopes** — token-level restrictions that limit what the token can do, independent of the user's role.
+3. **Role bindings** — the link between a principal, a role, and a workspace.
+4. **Scopes** — token-level restrictions that limit what the token can do, independent of the principal's role.
 
 ```text
 Request → PDP → Scope check → Role binding check → Allow / Deny
 ```
 
-For a request to succeed, both the scope check (does the token allow it?) and the role check (does the user have permission?) must pass.
+For a request to succeed, the role check must pass. If the token contains
+platform API scopes such as `intake:write` or `platform:read`, the scope check
+must pass too.
 
 For the full conceptual background, see [Authorization Concepts](/documentation/access-control/concepts). For the security architecture, see [Security Model](/documentation/access-control/security-model).
 

@@ -47,7 +47,10 @@ workspace = client.workspaces.create(
 </Tabs>
 ## Managing Workspace Members
 
-Members are users who have been granted access to a workspace. Each member has one of three roles:
+Members are principals that have been granted access to a workspace. A principal
+can be a human user, an IdP group, the wildcard principal `*`, or a NeMo service
+account such as `service-account:intake-otel-writer`. Each member has one of
+three roles:
 
 - **Viewer** — Read-only access to all resources
 - **Editor** — Can create, modify, and delete resources
@@ -62,7 +65,9 @@ When you add or change a member, the CLI and SDK wait for the change to propagat
 </Note>
 ### Add a Member
 
-Grant someone access to a workspace by adding them as a member with a specific role. The principal is typically an email address that identifies the user in your identity provider.
+Grant a principal access to a workspace by adding it as a member with a specific
+role. Human principals are often email addresses from your identity provider,
+but the principal value does not have to be an email address.
 
 <Tabs>
 
@@ -110,6 +115,53 @@ client.workspaces.members.create(
 </Tab>
 
 </Tabs>
+### Add a Service Account
+
+Service-account Scoped Access Keys authenticate as `service-account:<id>`.
+Create the role binding for that full principal value, not for the unprefixed
+service account ID:
+
+<Tabs>
+
+<Tab title="CLI">
+
+```bash
+nemo workspaces members create \
+  --principal service-account:intake-reader \
+  --roles Viewer \
+  --workspace ml-team
+```
+
+</Tab>
+<Tab title="Python SDK">
+
+```python
+from nemo_platform import NeMoPlatform
+
+client = NeMoPlatform()
+
+client.workspaces.members.create(
+    workspace="ml-team",
+    principal="service-account:intake-reader",
+    roles=["Viewer"],
+)
+```
+
+</Tab>
+
+</Tabs>
+
+Use the unprefixed ID only when creating the key with
+`nemo auth access-keys create --service-account intake-reader`. NeMo stamps the
+token subject as `service-account:intake-reader`.
+
+<Warning>
+
+Do not grant customer automation access with the `service:<name>` principal
+form. The `service:` prefix is reserved for internal platform service
+principals.
+
+</Warning>
 ### List Members
 
 View all members of a workspace to audit access or verify permissions. The response includes each member's principal, roles, and when access was granted.

@@ -11,6 +11,15 @@ The authoritative reference for NeMo Platform roles and their permissions. For b
 
 NeMo Platform provides human-facing roles for interactive users and a separate workload role for job runtime identities:
 
+<Note>
+
+The same workspace roles can be granted to NeMo service-account principals such
+as `service-account:intake-reader`. Service accounts are not internal
+`service:<name>` principals; grant them the minimum role needed for their
+automation task.
+
+</Note>
+
 **Viewer** — For stakeholders who need visibility into resources but should not modify them.
 
 - View all resources in a workspace (models, datasets, jobs, evaluations)

@@ -128,7 +128,7 @@ The PlatformAdmin role is granted via the `admin_email` config setting. See [Aut
 
 A role binding contains:
 
-- **Principal**: The user being granted access (e.g., `alice@company.com`)
+- **Principal**: The identity being granted access, such as a user, group, wildcard `*`, or service account
 - **Workspace**: The workspace where access is granted (e.g., `team-ml`)
 - **Role**: The role being assigned (e.g., `Editor`)
 
@@ -172,7 +172,9 @@ If a user tries to access a workspace they don't have permission for, the API re
 
 ## Policy Decision Point (PDP)
 
-Every authorized request is evaluated by the PDP, which checks role bindings and scopes. The PDP runs in one of two modes:
+Every authorized request is evaluated by the PDP, which checks role bindings and,
+when the token carries platform API scopes, scopes. The PDP runs in one of two
+modes:
 
 - **Embedded** (default): A WASM-based policy engine built into the auth service. No external dependencies.
 - **External OPA**: An Open Policy Agent instance (sidecar or standalone service) fetches policy bundles from the auth service.