Create host & enrollment code

Token scopes required: hosts:create, hosts:enroll

Request

application/json

Request Body required

• name string required

  Possible values: non-empty and <= 255 characters

  Name of the new host

• networkID string required

  ID of your network

• roleID string nullable

  ID of the role you want to assign

• ipAddress ipv4

  Assign an IP address to be used within the Managed Nebula network. Must be within the network's CIDR range. Will be chosen automatically if not provided.

• staticAddresses ipv4:port[]

  Default value: []

  List of static IPv4:port addresses. At least one is required if isLighthouse is true.

• listenPort integer

  Possible values: <= 65535

  Default value: 0

  The UDP port nebula should use on the host. An available port will be automatically selected if 0 is specified. Required for lighthouses and relays.

• isLighthouse boolean

  Set to true to create a new lighthouse. A Lighthouse cannot also be relay.

• isRelay boolean

  Set to true to create a new relay. A relay cannot also be a lighthouse.

Responses

• 200
• 400

---

Successful operation

application/json

• Schema
• Example (from schema)

---

Schema

• data object

  host object required

  id string

  organizationID string

  networkID string

  roleID string nullable

  name string

  ipAddress ipv4

  staticAddresses ipv4:port[]

  listenPort int64

  Will be zero if a regular host

  isLighthouse boolean

  Default value: false

  isRelay boolean

  Default value: false

  createdAt date-time

  isBlocked boolean

  Default value: false

  enrollmentCode object

  code string

  lifetimeSeconds int64
• metadata object

{
  "data": {
    "host": {
      "createdAt": "2023-01-25T18:15:27Z",
      "id": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
      "ipAddress": "100.100.0.29",
      "isBlocked": false,
      "isLighthouse": false,
      "isRelay": false,
      "listenPort": 0,
      "name": "Host 1",
      "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
      "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
      "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
      "staticAddresses": []
    },
    "enrollmentCode": {
      "code": "H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU",
      "lifetimeSeconds": 86400
    }
  },
  "metadata": {}
}

Validation error

application/json

• Schema
• Example (from schema)
• existingHostName
• cannotFindNetwork
• duplicateIpAddress
• cannotFindRole
• lighthouseXorRelay
• lighthouseNeedsStaticIP
• lighthouseNeedsStaticPort
• relayNeedsStaticPort

---

Schema

• errors object[] required

  Array [

  code string required

  A static name for the error type

  message string required

  A short human readable description of the error

  path string nullable

  Describes the variable missing or malformed

  ]

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "path": "string"
    }
  ]
}

A host already exists with the name.

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "name"
    }
  ]
}

Cannot find the supplied networkID.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "referenced value is invalid (perhaps it does not exist?)",
      "path": "networkID"
    }
  ]
}

A host with the ipAddress supplied already exists.

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "ipAddress"
    }
  ]
}

Cannot find the supplied roleID.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "referenced value is invalid (perhaps it does not exist?)",
      "path": "roleID"
    }
  ]
}

A host may be a lighthouse OR a relay, but not both.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must not also be relay hosts"
    }
  ]
}

A lighthouse requires at least one static IP address.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must have at least one static ip address",
      "path": "staticAddresses"
    }
  ]
}

A lighthouse requires a static listen port, like `4242`.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must specify a static listen port",
      "path": "listenPort"
    }
  ]
}

A relay requires a static listen port, like `4242`.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "relay hosts must specify a static listen port",
      "path": "listenPort"
    }
  ]
}

Loading...