# API keys and scopes

> Create API keys for scripts and CI, limit what they can do with scopes and projects, and revoke them.

Source: https://nodus-platform-site.pages.dev/docs/guides/access/api-keys-and-scopes/
Build revision: 211ad9f836655b1c3a2668c4693e442471f28614

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`.

Terminal window

```bash
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.

Terminal window

```bash
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

Terminal window

```bash
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.
