Create enrollment code

POST

/v1/hosts/{hostID}/enrollment-code

• Default server

Obtain a code that can be used with the dnclient enroll command on a host, lighthouse, or relay to enroll it into your Managed Nebula network.

It is not possible to enroll a host that is blocked, it must first be unblocked using the unblock endpoint.

Token scope required: hosts:enroll

Authorizations

• ApiToken
  hosts:enroll

Parameters

Path Parameters

hostID

required

string

Example

host-24NVITKMNU3CYCEDNFWKAOBX7I

Request Body

object

lifetimeSeconds

Lifetime of the enrollment code in seconds. Defaults to 86400 (24 hours).

integer format: int64

>= 60 <= 604800

Example

86400

Responses

200

Successful operation

object

data

required

object

code

required

Secret code to be used in dnclient enroll to allow the host/lighthouse/relay to join your Managed Nebula network.

string

lifetimeSeconds

required

The number of seconds the code is valid after being issued.

integer format: int64

Example

{
  "data": {
    "code": "H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU",
    "lifetimeSeconds": 86400
  }
}

400

Validation error

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

lifetimeSeconds is out of range.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be between 60 and 604800",
      "path": "lifetimeSeconds"
    }
  ]
}

The host is blocked.

{
  "errors": [
    {
      "code": "ERR_HOST_BLOCKED",
      "message": "cannot create enrollment code for blocked host - unblock the host to continue"
    }
  ]
}

The host was enrolled through an endpoint OIDC provider.

{
  "errors": [
    {
      "code": "ERR_NO_ENROLLMENT_CODE_FOR_ENDPOINT_HOST",
      "message": "cannot create enrollment code for an OIDC-enrolled host"
    }
  ]
}

401

The API key is missing, invalid or expired.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_UNAUTHORIZED",
      "message": "unauthorized"
    }
  ]
}

403

The API key lacks a required scope.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

The API key lacks a required scope.

{
  "errors": [
    {
      "code": "ERR_FORBIDDEN",
      "message": "api key must support the following scopes: hosts:read"
    }
  ]
}

404

Host not found

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_NOT_FOUND",
      "message": "resource not found"
    }
  ]
}

429

The organization has exceeded its API request rate limit. Retry the request after a short delay.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_TOO_MANY_REQUESTS",
      "message": "too many requests"
    }
  ]
}