Skip to content

API tokens: HTTP API

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.

Terminal window
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.

Terminal window
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_…"
}
Terminal window
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"
}
]
}

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:

Terminal window
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"
}
Terminal window
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:

Terminal window
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.