Skip to content

API tokens: the CLI from anywhere

On the manager host, norsk-mgr needs no token: it presents the proxy secret the host keeps for it. From anywhere else — your laptop, a scheduler, a CI job — the CLI needs an API token, sent as Authorization: Bearer on every request. This walkthrough mints a viewer token and an operator token, uses them from “elsewhere” (the same machine, but through NORSK_MGR_URL and NORSK_MGR_TOKEN rather than the loopback default), and reads back who did what. The Manager here has one local server registered so there is something to read and something to change.

token create takes a name — who or what will use it — and a role. viewer, the default, may look at everything and change nothing. A token never holds more than whoever minted it, and holds its role only while they still do. The token is printed once, on stdout by itself, so TOKEN=$(norsk-mgr token create ci --role viewer) captures exactly the token; the reminder goes to stderr. It is never shown again: the Manager stores a hash, not the secret. Every token expires: 90 days unless you give --expires-days N, a year at most.

Terminal window
norsk-mgr token create ci --role viewer
nmt_…
API token 'ci' (viewer, expires 2027-02-19T11:16:06.503Z) created — it will not be shown again. Use it as NORSK_MGR_TOKEN.

Two variables: NORSK_MGR_URL says which Manager, NORSK_MGR_TOKEN says who you are. Set them once in the environment (export …) or, as here, on the command. A read works:

Terminal window
NORSK_MGR_URL=http://127.0.0.1:9333 NORSK_MGR_TOKEN=nmt_… norsk-mgr nodes list
{
"items": [
{
"nodeId": "cluster-xqKu2+4aL8b55Qsi",
"state": "running",
"lastActivityAt": "2026-11-21T11:16:06.004Z",
"tags": {
"pool": "local",
"versionSkew": "none",
"workerProtocolVersion": "2.3",
"workerVersion": "0.1.0-2026-11-21-7114c45"
},
"createdAt": "2026-11-21T11:16:02.203Z",
"provider": {
"provider": "cluster"
},
"publicIpAddress": "127.0.0.1",
"privateIpAddress": "127.0.0.1",
"proxyUrl": "https://127.0.0.1",
"providerInstanceId": "cluster-xqKu2+4aL8b55Qsi",
"spare": false,
"unhealthy": false,
"warmFor": [],
"partiallyWarmFor": [],
"inventory": {
"totalCapacity": 8,
"utilizationCap": 1,
"totalCores": 8,
"gpus": [],
"capabilities": [
{
"name": "norsk.io/intel-qsv",
"count": 1
},
{
"name": "norsk.io/job-socket",
"count": 1
},
{
"name": "norsk.io/secret-references",
"count": 1
},
{
"name": "norsk.io/secret-references-runtime",
"count": 1
}
],
"reservedCapacity": 0,
"reservedCores": 0,
"reservedCapabilities": [],
"reachable": true,
"lastSeen": "2026-11-21T11:16:06.060Z",
"cordoned": false,
"assignedRuntimes": [],
"accessReplica": {
"version": 1795259760585,
"digest": "c372f8bcc47633b6a808851f33ce014ba0a364218d4b770229210f5dcfc702fd",
"vouchedAt": "2026-11-21T11:16:05.591Z",
"staleLimitMs": 28800000,
"ageMs": 1068,
"state": "current"
},
"secretsProfile": {
"name": "production",
"matchesManager": true
}
}
}
],
"nextCursor": null
}

A change does not. Cordoning a node is an operator’s job, and a viewer token is refused with a 403. The Manager judges a token it is given even from loopback, so a viewer token stays read-only wherever it is used.

Terminal window
NORSK_MGR_URL=http://127.0.0.1:9333 NORSK_MGR_TOKEN=nmt_… norsk-mgr nodes cordon cluster-xqKu2+4aL8b55Qsi
POST /api/v1/nodes/cluster-xqKu2%2B4aL8b55Qsi/cordon → 403: Your account does not hold the platform role this operation needs.

Mint an operator token for the job that needs one

Section titled “Mint an operator token for the job that needs one”

operator may run productions and work the nodes. Mint it on the manager host, in the UI under Settings, or with a token or account that holds at least operator — a viewer token cannot mint itself a wider one.

Terminal window
norsk-mgr token create deploy --role operator
nmt_…
API token 'deploy' (operator, expires 2027-02-19T11:16:06.876Z) created — it will not be shown again. Use it as NORSK_MGR_TOKEN.

The same cordon, with the operator token, goes through — and nodes get shows the node cordoned:

Terminal window
NORSK_MGR_URL=http://127.0.0.1:9333 NORSK_MGR_TOKEN=nmt_… norsk-mgr nodes cordon cluster-xqKu2+4aL8b55Qsi
{
"nodeId": "cluster-xqKu2+4aL8b55Qsi",
"action": "cordoned"
}
Terminal window
NORSK_MGR_URL=http://127.0.0.1:9333 NORSK_MGR_TOKEN=nmt_… norsk-mgr nodes get cluster-xqKu2+4aL8b55Qsi
{
"nodeId": "cluster-xqKu2+4aL8b55Qsi",
"state": "running",
"lastActivityAt": "2026-11-21T11:16:07.075Z",
"tags": {
"hold": "cordoned",
"pool": "local",
"versionSkew": "none",
"workerProtocolVersion": "2.3",
"workerVersion": "0.1.0-2026-11-21-7114c45"
},
"createdAt": "2026-11-21T11:16:02.203Z",
"provider": {
"provider": "cluster"
},
"publicIpAddress": "127.0.0.1",
"privateIpAddress": "127.0.0.1",
"proxyUrl": "https://127.0.0.1",
"providerInstanceId": "cluster-xqKu2+4aL8b55Qsi",
"spare": false,
"unhealthy": false,
"warmFor": [],
"partiallyWarmFor": [],
"inventory": {
"totalCapacity": 8,
"utilizationCap": 1,
"totalCores": 8,
"gpus": [],
"capabilities": [
{
"name": "norsk.io/intel-qsv",
"count": 1
},
{
"name": "norsk.io/job-socket",
"count": 1
},
{
"name": "norsk.io/secret-references",
"count": 1
},
{
"name": "norsk.io/secret-references-runtime",
"count": 1
}
],
"reservedCapacity": 0,
"reservedCores": 0,
"reservedCapabilities": [],
"reachable": true,
"lastSeen": "2026-11-21T11:16:06.060Z",
"cordoned": true,
"assignedRuntimes": [],
"accessReplica": {
"version": 1795259760585,
"digest": "c372f8bcc47633b6a808851f33ce014ba0a364218d4b770229210f5dcfc702fd",
"vouchedAt": "2026-11-21T11:16:05.591Z",
"staleLimitMs": 28800000,
"ageMs": 1540,
"state": "current"
},
"secretsProfile": {
"name": "production",
"matchesManager": true
}
}
}

Undo it, with the same token:

Terminal window
NORSK_MGR_URL=http://127.0.0.1:9333 NORSK_MGR_TOKEN=nmt_… norsk-mgr nodes uncordon cluster-xqKu2+4aL8b55Qsi
{
"nodeId": "cluster-xqKu2+4aL8b55Qsi",
"action": "uncordoned"
}

token list shows each token’s name, role, owner, id and dates — created, expiry, last used — and never the secret: your own tokens, or every token for an admin. The id is what revoke takes.

Terminal window
norsk-mgr token list
{
"items": [
{
"id": "6f02466b5c912451",
"name": "ci",
"role": "viewer",
"createdAt": "2026-11-21T11:16:06.503Z",
"expiresAt": "2027-02-19T11:16:06.503Z",
"lastUsedAt": "2026-11-21T11:16:06.763Z"
},
{
"id": "b0b65189e557e74a",
"name": "deploy",
"role": "operator",
"createdAt": "2026-11-21T11:16:06.876Z",
"expiresAt": "2027-02-19T11:16:06.876Z",
"lastUsedAt": "2026-11-21T11:16:07.234Z"
}
]
}

Revoking is immediate and final; a lost token is revoked and re-minted, never recovered. --yes skips the confirmation. The ci token goes:

Terminal window
norsk-mgr token revoke 6f02466b5c912451 --yes
{
"status": "ok",
"tokenId": "6f02466b5c912451"
}

Anything still holding it is refused from the next request on — a 401, not a 403, because the token is no longer recognised at all:

Terminal window
NORSK_MGR_URL=http://127.0.0.1:9333 NORSK_MGR_TOKEN=nmt_… norsk-mgr nodes list
GET /api/v1/nodes → 401: API token not recognised (revoked, expired or mistyped)

Every change the Manager records in its audit log carries the actor that made it: { kind: "token", name } for a request that came with an API token, { kind: "user", name } for a browser login, { kind: "local" } for the CLI on the manager host. The cordon and uncordon above are on record as deploy’s doing; minting and revoking tokens is audited too.

Terminal window
norsk-mgr audit list --limit 6
{
"integrityOk": true,
"entries": [
{
"seq": 17,
"timestampMs": 1795259767464,
"source": "norsk-mgr",
"sourceLabel": "Control plane",
"kind": "access-administration",
"summary": "token.revoke on 6f02466b5c912451 by host-admin",
"payload": "{\"time\":\"2026-11-21T11:16:07.463Z\",\"event\":\"access-administration\",\"change\":\"token.revoke\",\"target\":\"6f02466b5c912451\",\"attribution\":\"host-admin\",\"detail\":{\"name\":\"ci\"},\"actor\":{\"kind\":\"proxy\"}}",
"prevHash": "be095ea645198ff801e9422d42da7521565b70749b295460ed0a8f8bf84e7caa",
"hash": "4e80beb16cba1bb1802e7f75ff6e3e50a560ed06ee82a78b9b879aeb97e208f8"
},
{
"seq": 16,
"timestampMs": 1795259767464,
"source": "norsk-mgr",
"sourceLabel": "Control plane",
"kind": "token-revoked",
"summary": "Revoked API token \"ci\"",
"payload": "{\"name\":\"ci\",\"actor\":{\"kind\":\"proxy\"}}",
"prevHash": "a8e9f294013f9eeffcfb2ba387cbc2b54024ec631bb71ca50fc3e0847c8ce6fe",
"hash": "be095ea645198ff801e9422d42da7521565b70749b295460ed0a8f8bf84e7caa"
},
{
"seq": 15,
"timestampMs": 1795259767240,
"source": "norsk-mgr",
"sourceLabel": "Control plane",
"kind": "node-uncordoned",
"summary": "Uncordoned node \"cluster-xqKu2+4aL8b55Qsi\"",
"payload": "{\"nodeId\":\"cluster-xqKu2+4aL8b55Qsi\",\"actor\":{\"kind\":\"token\",\"name\":\"deploy\"}}",
"prevHash": "9074e79b74c3fcbf6ad1bf48bb937b84168dba454ebf3bafe80bb98f144549c3",
"hash": "a8e9f294013f9eeffcfb2ba387cbc2b54024ec631bb71ca50fc3e0847c8ce6fe"
},
{
"seq": 14,
"timestampMs": 1795259767034,
"source": "norsk-mgr",
"sourceLabel": "Control plane",
"kind": "node-cordoned",
"summary": "Cordoned node \"cluster-xqKu2+4aL8b55Qsi\"",
"payload": "{\"nodeId\":\"cluster-xqKu2+4aL8b55Qsi\",\"actor\":{\"kind\":\"token\",\"name\":\"deploy\"}}",
"prevHash": "c66b167d1a246923fb3ed8de416a1687b0847901d507a64e1d7e44fa01c8b2b1",
"hash": "9074e79b74c3fcbf6ad1bf48bb937b84168dba454ebf3bafe80bb98f144549c3"
},
{
"seq": 13,
"timestampMs": 1795259766920,
"source": "norsk-mgr",
"sourceLabel": "Control plane",
"kind": "access-administration",
"summary": "token.create on b0b65189e557e74a by host-admin",
"payload": "{\"time\":\"2026-11-21T11:16:06.920Z\",\"event\":\"access-administration\",\"change\":\"token.create\",\"target\":\"b0b65189e557e74a\",\"attribution\":\"host-admin\",\"detail\":{\"name\":\"deploy\",\"role\":\"operator\"},\"actor\":{\"kind\":\"proxy\"}}",
"prevHash": "074274fe37ac846d458638ece085da192e65205c3b37128e218157d2a9f06277",
"hash": "c66b167d1a246923fb3ed8de416a1687b0847901d507a64e1d7e44fa01c8b2b1"
},
{
"seq": 12,
"timestampMs": 1795259766920,
"source": "norsk-mgr",
"sourceLabel": "Control plane",
"kind": "token-created",
"summary": "Created API token \"deploy\" (operator)",
"payload": "{\"name\":\"deploy\",\"role\":\"operator\",\"actor\":{\"kind\":\"proxy\"}}",
"prevHash": "78979b4cd4acc3cdc0da8a20084c8b77a6c7023886037d6bf4ce16fc1463d125",
"hash": "074274fe37ac846d458638ece085da192e65205c3b37128e218157d2a9f06277"
}
]
}

Revoke the operator token as well once the job it was minted for is gone.

Terminal window
norsk-mgr token revoke b0b65189e557e74a --yes
{
"status": "ok",
"tokenId": "b0b65189e557e74a"
}

Captured 2026-11-21 against norsk-mgr 0.1.0-2026-11-21-7114c45, Norsk Manager 1.4.2-2026-11-19-3758b1eb — every command and screenshot on this page is from that run.