Create a service account for automation
Bootstrap a least-privilege service account and token for nr and CI
Service accounts are machine identities for CI/CD, agent VMs, and headless nr runs. Create the first service account in the dashboard (Access Control → Service Accounts) while signed in as a human. Agent install uses that JWT — not nr auth login on the VM.
See also Access control.
Chicken-and-egg bootstrap
Creating the first service account requires a human in the console (Access Control → Service Accounts). You can also run nr sa create from a laptop after nr auth login. Do not run OAuth on the agent VM. After that, automation and agent install use the service account JWT.
Recommended permissions for nr cluster register
Prefer a custom role over Owner. Minimum permissions:
| Permission | Purpose |
|---|---|
AgentService::CreateAgent | Create agent record |
AgentService::GetAgent | Poll status / provisioned |
AgentService::ListAgents | Reuse-by-name on conflict |
AgentService::GeneratePeeringConfig | Outbound Liqo peering |
AgentService::UploadInboundPeeringConfig | Inbound peering upload |
AgentService::GenerateInstallCommand | Only if using the UI install command |
AgentService::DeleteAgent | Only if using CLI deregister / cleanup |
OrganizationService::GetOrganization | Only if installing the operator (not --skip-operator-install) |
Stock Viewer is not enough. Owner / Administrator work but are broader than needed.
Create with the CLI
# 1. Create the service account (optional IP allowlist)
nr sa create \
--name ci-agent-register \
--description "Registers provider agents from CI" \
--allowed-ips 203.0.113.0/24 \
--output json
# 2. Assign a role (use your custom role ID from Access Control)
nr sa role assign \
--service-account-id <service-account-uuid> \
--role-id <role-uuid>
# 3. Generate a token (shown once — store it in your secret manager)
nr sa token generate \
--service-account-id <service-account-uuid> \
--name github-actions \
--expires-in-days 90nr sa is an alias for nr service-account.
Use the token
export NR_API_TOKEN="..."
echo $NR_API_TOKEN
nr agent list --org-id <org-uuid>
nr cluster register --name edge-ams-01 --agent-ip 203.0.113.10 --gateway-region AMS01 --org-id <org-uuid> --yesOr persist it for a dedicated automation user on a host:
nr auth set-token --from-envRotate and revoke
nr sa token list --service-account-id <service-account-uuid>
nr sa token revoke --token-id <token-uuid>Generate a new token, update CI secrets, then revoke the old one.