POST /v1/node-registrations
Self-register a node host (called by install-node.sh)
- operationId
registerNode- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Unauthenticated except for the registration credential in the body; rate limited per source IP (10/min) and globally (120/min) per control-api process. Creates a pending node (待初始化) named after the host and records the observed public source IP and OS details, then returns a one-time initial_enrollment token (10 minutes) for the Gateway enrollment. Dedupe: the node ID is a keyed hash of the machine fingerprint, so the same machine reuses its pending node (200) instead of creating a duplicate; once it has enrolled or been initialized the call returns 409 node_already_registered. A deleted (retired) node lets the machine register again as a new node. Self-registered nodes stay pending after enrollment and receive no configuration until an administrator sets admin_state=active. A new node gets the region of the region catalog when it has exactly one region, else an empty region.
Request body
application/json · Required：Yes
registerNode Request body| Name | Type | Required | Description |
|---|
credential | string | Yes | — |
|---|
machine_fingerprint | string | Yes | Lowercase hex SHA-256 of "cdnca-node-registration-v1" NUL machine-id NUL DMI product_uuid (empty when unreadable). |
|---|
hostname | string | No | — |
|---|
os_name | string | No | — |
|---|
kernel_version | string | No | — |
|---|
architecture | string | No | — |
|---|
Responses
registerNode Responses| Status | Description |
|---|
201 | Pending node created. Fields：node: Node enrollment_token: IssuedEnrollmentToken reused: boolean |
|---|
200 | Existing pending node of this machine reused; a fresh token is issued. Fields：node: Node enrollment_token: IssuedEnrollmentToken reused: boolean |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | invalid_registration_credential - the credential is invalid or was reset. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
429 | node_registration_rate_limited; retry after the Retry-After seconds. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/node-registrations/identity
Fetch the issued identity of an interrupted node install (called by install-node.sh --resume)
- operationId
recoverNodeRegistrationIdentity- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
For an install whose Gateway enrollment committed on the controller (certificate issued) but whose host never wrote its identity directory. Authenticated by the registration credential in the body and rate limited together with POST /v1/node-registrations (same per source IP and global window). Returns the live initial certificate of this machine's registered node whose enrollment CSR has the given SHA-256, in the agent.v1.EnrollResponse JSON shape; the Agent binds it to the private keys it kept in its pending enrollment state. Any miss (unknown machine, no issued certificate, CSR digest mismatch) is 404 node_identity_not_found, so the response never reveals whether another node exists. Every lookup of a registered machine is audited as node.registration.identity_fetch (success or denied). A node installed with a one-time enrollment token has no reusable credential and cannot use this endpoint.
Request body
application/json · Required：Yes
recoverNodeRegistrationIdentity Request body| Name | Type | Required | Description |
|---|
credential | string | Yes | — |
|---|
machine_fingerprint | string | Yes | The registration fingerprint sent to POST /v1/node-registrations. |
|---|
csr_sha256 | string | Yes | Lowercase hex SHA-256 of the CSR DER in the Agent's pending enrollment state (edge-agent enroll --print-pending-csr-sha256). |
|---|
Responses
recoverNodeRegistrationIdentity Responses| Status | Description |
|---|
200 | The issued identity of this machine. Fields：node_id: string(uuid) selected_protocol_version: object artifact_encryption_key_id: string certificate: object |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | invalid_registration_credential - the credential is invalid or was reset. |
|---|
404 | node_identity_not_found - no issued identity matches this machine and CSR digest. |
|---|
429 | node_registration_rate_limited; retry after the Retry-After seconds. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.404 The resource does not exist or belongs to another tenant.429 Rate limited: wait, then retry with lower concurrency.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list