Version 2.4.8 · latest

Node enrollment tokens node-enroll-tokens

Generates a one-time enrollment token and a one-line node install command, and looks up by id whether a node has used the token; the token is returned only once, when generated.

Pick an endpoint to see its example call on the right.

Node schedulingAuthentication: Admin only2 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

Node enrollment tokens object

FieldTypeDescription
commandstring One-line node install command, executable command only: includes the asset site URL, the control plane address and the trust root fingerprint --trust-sha256 (the node fetches the trust root bundle from control plane port 7444 and checks it against the fingerprint); the token is written by the shell builtin printf into a temporary directory created by mktemp -d and handed to the install script with --token-file, so it never appears in any process command line. Empty string when command_status is not ok.
command_statusstring Whether an install command could be built: ok = command is an executable command; no_mirror = the node package download URL is unavailable (no HTTPS asset site configured or it cannot be read, or this control plane does not yet have the signed release manifest of its own version to verify the install script); no_master_key = control plane keys are not initialized (rerun the control plane install command); master_addr_unknown = the control plane address could not be determined (set the node communication public address node.master_addr under System Admin › Upgrade & Maintenance › Node Communication, or open the panel through an address the nodes can reach).
Values ["ok","no_mirror","no_master_key","master_addr_unknown"]
expires_atstring Expires at
idstring Token id (not a credential): use it with GET /node-enroll-tokens/{token_id} to check whether a node has used the token.
internal_master_hoststring Set to the control plane address in the command when it is a loopback or private address (no node communication public address is configured and it was taken from the address used to open the panel), which nodes on other machines usually cannot reach; omitted otherwise.
node_idinteger Id of the node that enrolled with it (it then shows in the pending node list); omitted if unused.
tokenstring Plain text of the one-time enrollment token; shown only in this response.
token_in_commandboolean Whether the command contains the plain token (true = the command itself is a credential; do not paste it into tickets or logs); false when command_status is not ok.
usedboolean Whether a node has already enrolled with it (single use; void once used).
used_atstring When a node enrolled with it; omitted if unused.

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command