Create node enrollment

POST

/api/nodes

curl --request POST \
  --url https://gateway.example.com/api/nodes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "nginx", "hostname": "example", "displayName": "example", "folderId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "serviceAddresses": [ "example" ], "servicePort": 1 }'

• Your Gateway instance

Authorizations

• bearerAuth

Request Body^required

JSON request body

Media typeapplication/json

object

type

string

default: nginx

Allowed values: nginx bastion monitoring docker builder databases storage relay

hostname

required

string

>= 1 characters <= 255 characters

displayName

string

<= 255 characters

folderId

string | null format: uuid

serviceAddresses

Array<string>

<= 10 items

servicePort

integer

>= 1 <= 65535

Responses

201

Created

Media typeapplication/json

object

data

required

object

node

required

object

id

required

string format: uuid

type

required

string

Allowed values: nginx bastion monitoring docker builder databases storage relay

hostname

required

string

status

required

string

Allowed values: pending online offline error

key

additional properties

enrollmentToken

required

One-time enrollment token. Returned only once.

string

enrollmentTokenExpiresAt

Time after which the unused enrollment token is rejected.

string format: date-time

gatewayCertSha256

required

SHA-256 fingerprint of the active Gateway gRPC TLS leaf certificate.

string

/^sha256:[0-9a-f]{64}$/

gatewayEnrollmentTargets

required

Backend-derived gRPC enrollment targets. A null public gateway is not configured yet; installCommands then use the host of this request.

object

public

required

object

label

required

string

gateway

required

string | null

local

object

label

required

string

gateway

required

string

installerRelease

required

Gateway release whose installers the setup commands download and verify. Null for an unreleased build, whose commands run the installers from main.

string | null

installCommands

required

Setup command for each enrollment target, using curl or wget. A release build downloads the installer of its own release, checks it against gateway-daemon-installers.sha256 and pins the daemon release that matches this Gateway.

Array<object>

object

target

required

string

Allowed values: public local

label

required

string

gateway

required

string

curl

required

string

wget

required

string

Example

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "edge-01",
    "type": "nginx",
    "status": "online",
    "serviceCreationLocked": false
  }
}

400

Bad request

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "path": [
        "name"
      ],
      "message": "Required"
    }
  ]
}

401

Authentication required

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "UNAUTHORIZED",
  "message": "Authentication required"
}

403

Forbidden

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions"
}

404

Not found

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "NOT_FOUND",
  "message": "Resource not found"
}

409

Conflict

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "CONFLICT",
  "message": "Resource already exists"
}

422

Unprocessable entity

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "Request could not be processed"
}

500

Internal server error

Media typeapplication/json

object

code

required

Error code

string

message

required

Human-readable error message

string

details

Additional error details

Example

{
  "code": "INTERNAL_ERROR",
  "message": "Internal server error"
}