Using Authentication

How to log in, make authenticated API calls, manage tokens, and create Scoped Access Keys with the CLI and SDK.

Prerequisites: For OIDC login, configure an identity provider first. See OIDC. For local testing without OIDC, use nemo auth login --unsigned-token --email <email>. Scoped Access Keys also require the administrator to enable auth.access_keys.enabled; see Authentication Configuration.

Log In

The device flow is the recommended login method. It opens your browser to authenticate with your organization’s identity provider.

$
nemo auth login

Expected output:

To sign in, use a web browser to open the page https://microsoft.com/devicelogin
and enter the code ABCD-EFGH to authenticate.
Waiting for authentication...

Open the URL, enter the code, and sign in with your IdP credentials. After consent, verify:

$
nemo auth status

Authentication Status
Cluster             https://nmp.company.com
Context             default
Config File         /home/alice/.config/nmp/config.yaml
Auth Type           oauth
Credential Source   config file
Email               alice@company.com
Scopes              platform:read platform:write
Expires             2026-02-15T14:30:00+00:00 (1h 0m remaining)
Refresh Token       available (run 'nemo auth refresh' to renew)
Token               eyJhbGciOiJSUzI1NiIs...abc1234567

All CLI and SDK commands now use the stored token automatically.

Requesting Specific Scopes

By default, the CLI requests the scopes configured in auth.oidc.default_scopes (typically platform:read platform:write plus OIDC standard scopes like openid profile email offline_access). Restrict the token’s access by specifying fewer scopes:

$
nemo auth login --scope "platform:read"

See API Scopes for the full list of available scopes.

Non-Interactive Login (CI/CD)

For CI pipelines, use the password grant to obtain a token without a browser: nemo auth login --username <user> --password <pass> (or set NMP_OIDC_USERNAME / NMP_OIDC_PASSWORD environment variables). If your CI system can obtain tokens directly (e.g., workload identity federation), pass the token via access_token as shown in Make API Calls below.

Make API Calls

Python SDK

The SDK reads credentials from the CLI config automatically — no manual token handling needed:

1
from nemo_platform import NeMoPlatform
2
3
# After `nemo auth login` (OIDC) or `nemo auth login --unsigned-token --email <email>` (quickstart),
4
# the SDK reads base_url, workspace, and the stored token from the CLI config.
5
# This is the recommended pattern for interactive / OIDC-authenticated usage.
6
client = NeMoPlatform()
7
8
workspaces = client.workspaces.list()

If you need explicit token control (for example, a token from a CI system or environment variable), pass it via access_token:

1
import os
2
from nemo_platform import NeMoPlatform
3
4
client = NeMoPlatform(
5
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
6
    workspace="default",
7
    access_token=os.environ.get("NMP_ACCESS_TOKEN"),
8
)

HTTP (curl)

$
TOKEN=$(nemo auth token)
$
curl -H "Authorization: Bearer $TOKEN" \
>
 https://nmp.company.com/apis/entities/v2/workspaces

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:

$
# Create a Scoped Access Key with the platform default expiry and print the token once.
$
nemo auth access-keys create --name ci-build

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.

create prints the Scoped Access Key token once. Store it in your secret manager and send it in the standard Authorization header:

$
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 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 allowed unlimited keys. Revocation and rotation are not implemented.

Token Inspection

Retrieve the raw JWT for debugging or use in other clients:

$
nemo auth token

Decode the token to inspect claims:

$
nemo auth token --decode

Key claims to check:

• 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)

Token Management

How Auto-Refresh Works

You never need to refresh tokens manually — the CLI and SDK handle it transparently:

• SDK: Refreshes lazily before each API call when the token is within 60 seconds of expiry. No background threads or timers — the cost is paid only when a refresh is actually needed (typically once per hour). Multiple NeMoPlatform() clients in the same Python process share a single token, so only one refresh happens even with many clients.
• CLI: Checks the token before every command and refreshes if it expires within 5 minutes. To disable for a specific command: nemo --no-auto-refresh workspaces list.

Running multiple scripts or CLI commands simultaneously is safe — file-level locking prevents conflicts when refreshing tokens across processes.

If the refresh token itself has expired (e.g., after days of inactivity), re-login with nemo auth login.

Manual Refresh and Logout

$
# Force a token refresh
$
nemo auth refresh
$
$
# Clear stored tokens
$
nemo auth logout

Config File

Tokens are stored in ~/.config/nmp/config.yaml:

1
users:
2
  - name: default
3
    type: oauth
4
    token: "<access_token_jwt>"
5
    refresh_token: "<refresh_token>"

The OIDC token endpoint is not stored — it is discovered at runtime from your cluster’s /apis/auth/discovery endpoint. This keeps the config portable across environments.

Related

• OIDC — Configure your identity provider.
• API Scopes — Scope model and available scopes.
• Security Model — Trust boundaries and the principal model.
• Troubleshooting — Fix common 401/403 errors and login failures.