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.
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.
/api/v2/node-enroll-tokensCreate node enrollment token
Authentication: Admin only
/api/v2/node-enroll-tokens/{token_id}Get node enrollment token status
Authentication: Admin only
Node enrollment tokens object
| Field | Type | Description |
|---|---|---|
command | string | 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_status | string | 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). |
expires_at | string | Expires at |
id | string | 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_host | string | 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_id | integer | Id of the node that enrolled with it (it then shows in the pending node list); omitted if unused. |
token | string | Plain text of the one-time enrollment token; shown only in this response. |
token_in_command | boolean | 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. |
used | boolean | Whether a node has already enrolled with it (single use; void once used). |
used_at | string | 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.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"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"
}