Using Authentication#

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

Prerequisites: OIDC must be configured on the platform. See OIDC Setup.

Log In#

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

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

nmp auth status

Logged in as alice@company.com
Scopes: platform:read platform:write
Token expires: 2026-02-15T14:30:00Z

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:

nmp 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: nmp 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.

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.

Make API Calls#

Python SDK#

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

from nemo_platform import NeMoPlatform

# After `nmp auth login` (OIDC) or `nmp auth login --unsigned-token ...` (quickstart),
# the SDK reads base_url, workspace, and the stored token from the CLI config.
# This is the recommended pattern for interactive / OIDC-authenticated usage.
client = NeMoPlatform()

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:

import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
    access_token=os.environ.get("NMP_ACCESS_TOKEN"),
)

HTTP (curl)#

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

Token Inspection#

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

nmp auth token

Decode the token to inspect claims:

nmp auth token | cut -d. -f2 | base64 -d 2>/dev/null | python -m json.tool

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: nmp --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 nmp auth login.

Manual Refresh and Logout#

# Force a token refresh
nmp auth refresh

# Clear stored tokens
nmp auth logout

Config File#

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

users:
  - type: oauth
    name: default
    token: "<access_token_jwt>"
    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.