API tokens: HTTP API
Before you start
Section titled “Before you start”Every operator endpoint is under /api/v1. On the Manager host, a request that presents the host’s proxy secret (the file norsk-mgr itself reads) is the host administrator, which is the bootstrap path for the first token. Every other caller sends a token as a bearer secret, and a token never holds more than whoever minted it.
Create the first credential
Section titled “Create the first credential”curl --silent --show-error --fail-with-body --request POST --header 'Accept: application/json' --header 'X-Norsk-Proxy: $(cat ~/.norsk-mgr/proxy-secret)' --header 'Content-Type: application/json' --data '{"name":"deployment automation","role":"operator","expiresInDays":30}' http://127.0.0.1:9333/api/v1/tokens{ "id": "4ebe6d1ce6374237", "name": "deployment automation", "role": "operator", "createdAt": "2026-11-21T11:16:17.417Z", "expiresAt": "2026-12-21T11:16:17.417Z", "token": "nmt_…"}A token may mint another, never wider than itself. The secret is returned only by this 201 response; later list requests contain metadata only.
curl --silent --show-error --fail-with-body --request POST --header 'Accept: application/json' --header 'Authorization: Bearer nmt_…' --header 'Content-Type: application/json' --data '{"name":"monitoring","role":"viewer"}' http://127.0.0.1:9333/api/v1/tokens{ "id": "f293bd2d6beb1e2d", "name": "monitoring", "role": "viewer", "parent": "4ebe6d1ce6374237", "createdAt": "2026-11-21T11:16:17.440Z", "expiresAt": "2026-12-21T11:16:17.417Z", "token": "nmt_…"}curl --silent --show-error --fail-with-body --request GET --header 'Accept: application/json' --header 'Authorization: Bearer nmt_…' http://127.0.0.1:9333/api/v1/tokens{ "items": [ { "id": "f293bd2d6beb1e2d", "name": "monitoring", "role": "viewer", "parent": "4ebe6d1ce6374237", "createdAt": "2026-11-21T11:16:17.440Z", "expiresAt": "2026-12-21T11:16:17.417Z" } ]}Roles are enforced on every request
Section titled “Roles are enforced on every request”A token sees and revokes its own credentials; another principal’s are account administration. The viewer token is refused revoking the operator token, with the standard error envelope and 403, and may revoke itself:
curl --silent --show-error --fail-with-body --request DELETE --header 'Accept: application/json' --header 'Authorization: Bearer nmt_…' http://127.0.0.1:9333/api/v1/tokens/4ebe6d1ce6374237{ "status": "error", "code": "TOKEN_WRITE_FORBIDDEN", "message": "Revoking another principal's token is account administration"}curl --silent --show-error --fail-with-body --request DELETE --header 'Accept: application/json' --header 'Authorization: Bearer nmt_…' http://127.0.0.1:9333/api/v1/tokens/f293bd2d6beb1e2d{ "status": "ok", "tokenId": "f293bd2d6beb1e2d"}Finally, revoke the bootstrap credential on the Manager host:
curl --silent --show-error --fail-with-body --request DELETE --header 'Accept: application/json' --header 'X-Norsk-Proxy: $(cat ~/.norsk-mgr/proxy-secret)' http://127.0.0.1:9333/api/v1/tokens/4ebe6d1ce6374237{ "status": "ok", "tokenId": "4ebe6d1ce6374237"}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.