Authenticate

The CLI talks to the same NodeRings API as the dashboard. Agent VMs and CI must use a service account token. nr auth login is for a laptop (for example creating the first service account), not for installing an agent.

Method	Typical use
Service account token (`NR_API_TOKEN` / `nr auth set-token`)	Agent VMs, CI, scheduled jobs
`nr auth login`	Laptop or bastion with a browser — not the agent VM

Your provider organization must be verified before agent APIs succeed. nr cluster register requires --org-id (or NR_ORGANIZATION_ID) in addition to a token. --org-id only sends X-Organization-ID; it cannot authenticate and cannot grant access to an organization the token does not belong to.

Service account token (agent VM)

In the console, open Access Control → Service Accounts, create a service account in the provider organization, and generate a token (How to: Service accounts).
On the agent VM:

export NR_API_TOKEN="..."
echo $NR_API_TOKEN
nr auth status

Or store it in the local config file (mode 0600):

nr auth set-token --token "..."
# or
export NR_API_TOKEN="..."
nr auth set-token --from-env

Interactive OAuth (laptop only)

nr auth login

Optional flags:

Flag	Purpose
`--no-browser`	Print the URL; open it on another device
`--force`	Re-authenticate even if a valid token exists
`--browser`	Prefer a specific browser binary (when auto-detect is wrong)

Check and refresh:

nr auth status
nr auth refresh
nr auth logout

Do not run this flow on the agent VM. OAuth binds to your home organization (often a client org) and the CLI no longer auto-selects a provider tenant.

Token priority

When more than one credential is present, the CLI resolves in this order:

Environment: NR_API_TOKEN, then NODERINGS_API_TOKEN, then NR_TOKEN, then NODERINGS_TOKEN
auth.token in ~/.nr/config.yaml
OS keyring / OAuth token file (auth.token_file, default ~/.nr/tokens)

Organization id

nr cluster register requires --org-id (copy-paste from Create agent in the console). Other commands send the header when --org-id or NR_ORGANIZATION_ID is set. Service-account JWTs are already scoped to one organization; the header must match that tenant or the API returns forbidden.

Override the API URL

Production default is https://api.noderings.com. Override when needed:

nr --api-url https://api.noderings.com auth status
# or
export NR_API_URL=https://api.noderings.com

Full precedence: Configuration reference.