API keys and scopes

An API key lets a script, a notebook or CI call Nodus as you. Keys look like nodus_sk_live_… and are sent as Authorization: Bearer <key>, or through NODUS_API_KEY.

nodus create apikey notebook

The key is printed once, alone on standard output, so KEY=$(nodus create apikey notebook) captures it. Nodus stores only a keyed hash of it, so a lost key cannot be shown again: delete it and create a new one. -o json or -o yaml prints the whole object, key included.

Scopes

A key’s scopes limit what it can do. The default, *, means “whatever my role allows”, and it follows your role: if your role changes, the key changes with it.

nodus create apikey ci --scopes jobs:write,volumes:read --projects research --expires 720h
nodus auth can-i create sandboxes    # run with the key to check it

Scopes are <resource>:read or <resource>:write (write includes read), plus *:read for read-only access to everything. A key can never hold more than its creator’s role: asking for more is refused with 403 naming the scopes you lack. A key created with another key (or by a connected agent) can hold only what that credential holds, so it cannot ask for * or *:read unless the creating credential has them itself.

--scopes and --projects take comma-separated lists, and --description says what the key is for. To mint a key for CI that survives its creator, bind it to a service account of the project you work in with --service-account NAME.

A key restricted with --projects reaches only those projects, and it cannot change org-level settings. If every project it was restricted to is deleted, it reaches no project at all. A key bound to a service account can only be restricted to that service account’s project.

List and revoke

nodus get apikeys
nodus delete apikey ci

A deleted key stops working within 30 seconds everywhere. Listing shows the key’s prefix (nodus_sk_live_01j9…), scopes, owner, last use and expiry, never the key itself. Members can delete their own keys. Deleting another member’s key takes an Admin or Owner, and deleting a service account’s key takes permission to manage service accounts in its project.

Keys the CLI creates

nodus login creates one key per org, named cli-<host>-<date>, with every scope your role grants, valid for 90 days and labelled as launched by the CLI. nodus logout revokes it.

If a key leaks

Delete it. Keys are registered with GitHub secret scanning, so a key pushed to a public repository is reported to us and revoked.