Skip to content

Edit network

PUT
/v2/networks/{networkID}

Edit an existing network.

Caution: Any properties not provided in the request will be reset to their default values.

Token scope required: networks:update

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
networkID
required
string
Example
network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY

Request Body required

Section titled “Request Body required ”
object
name
required

Name of the network

string
>= 1 characters <= 255 characters
Example
Management
description

Optional description of the network

string
<= 255 characters
Example
This network allows the ops team to manage infrastructure
lighthousesAsRelays
required

Should the lighthouses in this network be configured as relays?

This applies to the managed lighthouse as well as to any lighthouse you run yourself. When enabled on a network using the managed lighthouse, traffic between hosts that cannot connect directly may be relayed through Defined Networking’s infrastructure. Relayed traffic remains encrypted end-to-end between the two hosts.

boolean
disableManagedLighthouses

Opt this network out of the managed lighthouse. Defaults to false, meaning Defined Networking runs a lighthouse for the network.

Set this to true only if you run your own lighthouses; a network with no reachable lighthouse cannot perform peer discovery.

Managed lighthouses require an IPv6-capable network, so this field has no effect on networks with a certVersion of 1.

boolean

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful operation

object
data
required
object
id
required
string
organizationID
required
string
signingCAID
required

The ID of the Certificate Authority being used.

string
name
required
string
description
required
string
cidrs
required

List of CIDR prefixes assigned to this network. IPv4-only networks have exactly one IPv4 entry. IPv6-capable networks always have an IPv6 CIDR and optionally an IPv4 CIDR.

Array<string>
certVersion
required

Certificate version used by this network. Version 2 is required for IPv6 support. Known values are 1 and 2. New values may be added, so clients should accept values not listed here.

integer
lighthousesAsRelays
required
boolean
disableManagedLighthouses
required

Whether this network has opted out of the managed lighthouse. When false, Defined Networking runs a lighthouse for the network and no lighthouse of your own is required.

boolean
curve
required

Cryptographic curve used by the network’s certificates. Known values are 25519 and P256. New values may be added, so clients should accept values not listed here.

string
hostCount
required
integer
createdAt
required
string format: date-time
Example
{
  "data": {
    "id": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
    "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
    "signingCAID": "ca-TRJSVAAAPJXTOICJMG2KZBKQEE",
    "name": "Management",
    "description": "This network allows the ops team to manage infrastructure",
    "cidrs": [
      "192.168.4.0/22",
      "fdef:c0:c0:1::/80"
    ],
    "certVersion": 2,
    "hostCount": 27,
    "lighthousesAsRelays": false,
    "disableManagedLighthouses": false,
    "curve": "25519",
    "createdAt": "2023-02-14T20:34:59Z"
  }
}

400

Section titled “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 network already exists with the name.

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

401

Section titled “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

Section titled “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

Section titled “404 ”

Network 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

Section titled “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"
    }
  ]
}