Authentication

The portal signs you in with a session cookie. Anything else (a script, a CI job, the Terraform provider) uses an API token.

Issuing a token

Settings → Tokens → API tokens, as an admin or owner. API tokens come with the Business and Enterprise plans. Give it a name, the scopes it needs and, if you like, an expiry. The value starts upd_ and is shown once: only its SHA-256 is stored, so a lost token can’t be shown again. Revoke it and issue another.

Using it

Send it as a bearer token to any route under /v1/orgs/{org}:

curl -H "Authorization: Bearer upd_..." \
  https://api.updawg.net/v1/orgs/acme/hosts

A token belongs to one organization. Asked about another, it gets 404, the same answer as for an organization that doesn’t exist. Requests made with a token need no CSRF header; that is only for the portal’s cookie.

What a token may do

A token acts as the person who issued it, with their current role, and only within its scopes. Demote that person and the token can do less; remove them from the organization and it stops working.

Scope	Lets the token
read	Read the fleet: hosts, updates, proposals, jobs
comment	Comment on proposals
approve	Approve proposals
rollout	Resume and stop rollouts
jobs	Propose reboots and agent updates, plan release upgrades, run preflights
policy	Edit policies
groups	Manage host groups
hosts	Rename, relabel, annotate and decommission hosts
enrollment	Issue and revoke enrollment tokens
audit	Read the audit log
integrations	Manage notification channels and rules

A token can only be given scopes its issuer’s role allows. Some things have no scope at all and need a person signed in to the portal: members and invitations, API tokens themselves, signing keys, billing, single sign-on, audit log retention, and deleting the organization.

A token asking for something outside its scopes gets 403 with the type insufficient-scope. See errors.