Edit join key

PATCH

/v1/join-keys/{joinKeyID}

• Default server

Change a join key’s name or expiration. Its network, role, tags, and address prefixes can’t be changed; create a new key instead. Omitted properties keep their current values.

Token scope required: join-keys:update

Authorizations

• ApiToken
  join-keys:update

Parameters

Path Parameters

joinKeyID

required

string

Example

dnjoin-P3RCTXN5LVFGBMJNYF2QHKWDOA

Request Body ^required

Only a join key’s name and expiration can be changed. Omitted properties keep their current values, and other properties, such as networkID, are ignored.

object

name

Must be a DNS label: lowercase letters, digits, and hyphens, not starting or ending with a hyphen. Must be unique within the organization. Can’t be null.

string

>= 1 characters <= 54 characters /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/

Example

ci-runner

expiresAt

When the key stops enrolling hosts. Must be in the future. null removes the expiration.

string | null format: date-time

Example

2027-06-01T00:00:00Z

Example

{
  "expiresAt": "2027-06-01T00:00:00Z"
}

Responses

200

Successful operation

object

data

required

object

id

required

string

Example

dnjoin-P3RCTXN5LVFGBMJNYF2QHKWDOA

organizationID

required

string

Example

org-F63A24JGCLJV3ZEUTLCBISGETA

name

required

Identifies the key. Hosts that enroll without reporting a usable hostname are named after it, followed by a random suffix.

string

Example

ci-runner

networkID

required

Network that hosts enrolled with this key join.

string

Example

network-KAOWMXZHZWCVMGGFKM22XEGYLE

roleID

required

Role assigned to hosts enrolled with this key.

string | null

Example

role-PZEDBXHCEXKAKJPZ6XOQTIAJA4

tags

required

Tags assigned to hosts enrolled with this key.

Array<string>

Example

[
  "env:ci"
]

autoAssignCIDRs

required

Prefixes from which hosts enrolled with this key are assigned addresses. Includes the network’s IPv6 prefix whenever the network has one.

array | null

Example

[
  "100.100.0.0/22",
  "fdef:c0:c0:1::/80"
]

expiresAt

required

When the key stops enrolling hosts. null means the key does not expire.

string | null format: date-time

Example

2027-01-01T00:00:00Z

createdAt

required

string format: date-time

Example

2026-10-29T15:00:00Z

modifiedAt

required

string format: date-time

Example

2026-10-29T15:00:00Z

Example

{
  "data": {
    "id": "dnjoin-P3RCTXN5LVFGBMJNYF2QHKWDOA",
    "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
    "name": "ci-runner",
    "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
    "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
    "tags": [
      "env:ci"
    ],
    "autoAssignCIDRs": [
      "100.100.0.0/22",
      "fdef:c0:c0:1::/80"
    ],
    "expiresAt": "2027-06-01T00:00:00Z",
    "createdAt": "2026-10-29T15:00:00Z",
    "modifiedAt": "2026-10-30T09:00:00Z"
  }
}

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

A join key already exists with the name.

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

The name is not a DNS label.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must contain only lowercase letters, digits, and hyphens, and must not start or end with a hyphen",
      "path": "name"
    }
  ]
}

`expiresAt` is not in the future.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be in the future",
      "path": "expiresAt"
    }
  ]
}

The network or role does not exist. Not returned on update.

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

An `autoAssignCIDRs` entry is an address rather than a CIDR prefix. Not returned on update.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be a CIDR prefix, not an address",
      "path": "autoAssignCIDRs[0]"
    }
  ]
}

An `autoAssignCIDRs` entry isn't exactly the network's IPv4 CIDR or IPv6 prefix. Not returned on update.

{
  "errors": [
    {
      "code": "ERR_OUT_OF_RANGE",
      "message": "CIDR prefix does not match the network's IPv4 CIDR",
      "path": "autoAssignCIDRs[0]"
    }
  ]
}

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

Join key 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"
    }
  ]
}