1929 lines
71 KiB
YAML
1929 lines
71 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
version: 1.0.0
|
|
description: |
|
|
<br/>
|
|
<br/>
|
|
|
|
This API enables automated administration of Defined Networking hosts, roles, logs, and more.
|
|
|
|
To authenticate, obtain an api key to use as a bearer token from your Defined Networking admin panel [API Keys page](https://admin.defined.net/settings/api-keys). API keys must be given the appropriate permission scopes for every method and endpoint, as specified throughout this documentation.
|
|
|
|
Please [contact us](https://www.defined.net/contact?reason=support) for any questions or issues.
|
|
|
|
In the event of a token leak, please take care to [rotate the key](/guides/rotating-api-keys).
|
|
|
|
<div className='introduction-end'></div>
|
|
title: Defined Networking API
|
|
termsOfService: http://defined.net/terms/
|
|
contact:
|
|
url: https://www.defined.net/contact?reason=support
|
|
x-logo:
|
|
url: https://docs.defined.net/img/logo.svg
|
|
altText: Defined Networking logo
|
|
x-dark-logo:
|
|
url: https://docs.defined.net/img/logo-dark.svg
|
|
altText: Defined Networking logo
|
|
servers:
|
|
- url: https://api.defined.net
|
|
description: Default server
|
|
security:
|
|
- ApiToken: []
|
|
tags:
|
|
- name: hosts
|
|
x-displayName: Hosts
|
|
description: Operations requiring `hosts:` permission scopes
|
|
- name: roles
|
|
x-displayName: Roles
|
|
description: Operations requiring `roles:` permission scopes
|
|
- name: auditLogs
|
|
x-displayName: Audit Logs
|
|
description: Operations requiring `audit-logs:` permission scopes
|
|
- name: networks
|
|
x-displayName: Networks
|
|
description: Operations requiring `networks:` permission scopes
|
|
- name: downloads
|
|
x-displayName: Downloads
|
|
description: Information about software downloads
|
|
externalDocs:
|
|
description: Find more about the API here
|
|
url: https://docs.defined.net/guides/automating-host-creation/
|
|
paths:
|
|
/v1/hosts:
|
|
post:
|
|
summary: Create host
|
|
description: |
|
|
Create a new host, lighthouse, or relay.
|
|
|
|
Token scope required: `hosts:create`
|
|
|
|
### Request
|
|
operationId: hostCreate
|
|
tags:
|
|
- hosts
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- name
|
|
- networkID
|
|
properties:
|
|
name:
|
|
description: Name of the new host
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 255
|
|
example: My new host
|
|
networkID:
|
|
description: ID of your network
|
|
type: string
|
|
example: network-KAOWMXZHZWCVMGGFKM22XEGYLE
|
|
roleID:
|
|
description: ID of the role you want to assign
|
|
type: string
|
|
nullable: true
|
|
example: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
|
|
ipAddress:
|
|
description: 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.
|
|
type: string
|
|
format: ipv4
|
|
example: 100.100.0.29
|
|
staticAddresses:
|
|
description: List of static IPv4:port addresses. At least one is required if `isLighthouse` is `true`.
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: ipv4:port
|
|
example:
|
|
- 84.123.10.1:4242
|
|
default: []
|
|
listenPort:
|
|
description: 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.
|
|
format: integer
|
|
minimum: 0
|
|
maximum: 65535
|
|
default: 0
|
|
isLighthouse:
|
|
description: Set to true to create a new lighthouse. A Lighthouse cannot also be relay.
|
|
format: boolean
|
|
isRelay:
|
|
description: Set to true to create a new relay. A relay cannot also be a lighthouse.
|
|
format: boolean
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Host'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
createdAt: '2023-01-25T18:15:27Z'
|
|
id: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
ipAddress: 100.100.0.29
|
|
isBlocked: false
|
|
isLighthouse: false
|
|
isRelay: false
|
|
listenPort: 0
|
|
name: My new host
|
|
networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
roleID: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
|
|
staticAddresses:
|
|
- 84.123.10.1:4242
|
|
metadata:
|
|
lastSeenAt: '2023-01-25T18:15:27Z'
|
|
platform: dnclient
|
|
updateAvailable: false
|
|
version: 0.1.9
|
|
metadata: {}
|
|
'400':
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
$ref: '#/components/schemas/Errors'
|
|
examples:
|
|
existingHostName:
|
|
summary: A host already exists with the name.
|
|
value:
|
|
errors:
|
|
- code: ERR_DUPLICATE_VALUE
|
|
message: value already exists
|
|
path: name
|
|
cannotFindNetwork:
|
|
summary: Cannot find the supplied networkID.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_REFERENCE
|
|
message: referenced value is invalid (perhaps it does not exist?)
|
|
path: networkID
|
|
duplicateIpAddress:
|
|
summary: A host with the ipAddress supplied already exists.
|
|
value:
|
|
errors:
|
|
- code: ERR_DUPLICATE_VALUE
|
|
message: value already exists
|
|
path: ipAddress
|
|
cannotFindRole:
|
|
summary: Cannot find the supplied roleID.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_REFERENCE
|
|
message: referenced value is invalid (perhaps it does not exist?)
|
|
path: roleID
|
|
lighthouseXorRelay:
|
|
summary: A host may be a lighthouse OR a relay, but not both.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: lighthouse hosts must not also be relay hosts
|
|
lighthouseNeedsStaticIP:
|
|
summary: A lighthouse requires at least one static IP address.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: lighthouse hosts must have at least one static ip address
|
|
path: staticAddresses
|
|
lighthouseNeedsStaticPort:
|
|
summary: A lighthouse requires a static listen port, like `4242`.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: lighthouse hosts must specify a static listen port
|
|
path: listenPort
|
|
relayNeedsStaticPort:
|
|
summary: A relay requires a static listen port, like `4242`.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: relay hosts must specify a static listen port
|
|
path: listenPort
|
|
get:
|
|
summary: List hosts
|
|
description: |
|
|
Get a paginated list of hosts, lighthouses, and relays.
|
|
|
|
Token scope required: `hosts:list`
|
|
|
|
### Request
|
|
operationId: hostsList
|
|
tags:
|
|
- hosts
|
|
parameters:
|
|
- $ref: '#/components/parameters/includeCounts'
|
|
- $ref: '#/components/parameters/cursor'
|
|
- $ref: '#/components/parameters/pageSize'
|
|
- $ref: '#/components/parameters/filter-isBlocked'
|
|
- $ref: '#/components/parameters/filter-isLighthouse'
|
|
- $ref: '#/components/parameters/filter-isRelay'
|
|
- $ref: '#/components/parameters/filter-metadata-lastSeenAt'
|
|
- $ref: '#/components/parameters/filter-metadata-platform'
|
|
- $ref: '#/components/parameters/filter-metadata-updateAvailable'
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Host'
|
|
metadata:
|
|
$ref: '#/components/schemas/PaginationMetadata'
|
|
examples:
|
|
noParams:
|
|
summary: When <code>includeCounts</code> parameter is not set to true
|
|
value:
|
|
data:
|
|
- 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: []
|
|
metadata:
|
|
lastSeenAt: '2023-04-05T17:19:42Z'
|
|
platform: dnclient
|
|
updateAvailable: false
|
|
version: 0.1.9
|
|
metadata:
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
includeCounts:
|
|
summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
|
|
value:
|
|
data:
|
|
- 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: []
|
|
metadata:
|
|
lastSeenAt: '2023-04-05T17:19:42Z'
|
|
platform: mobile
|
|
updateAvailable: true
|
|
version: 0.1.9
|
|
metadata:
|
|
totalCount: 500
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
page:
|
|
count: 1
|
|
start: 5
|
|
/v1/hosts/{hostID}:
|
|
get:
|
|
summary: Get host
|
|
description: |
|
|
Fetch information about a particular host, lighthouse, or relay.
|
|
|
|
Token scope required: `hosts:read`
|
|
|
|
### Request
|
|
operationId: hostGet
|
|
tags:
|
|
- hosts
|
|
parameters:
|
|
- name: hostID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Host'
|
|
metadata:
|
|
type: object
|
|
examples:
|
|
Example:
|
|
value:
|
|
data:
|
|
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: []
|
|
metadata:
|
|
lastSeenAt: '2023-04-05T17:19:42Z'
|
|
platform: dnclient
|
|
updateAvailable: false
|
|
version: 0.1.9
|
|
metadata: {}
|
|
noMetadata:
|
|
summary: If the host has not been enrolled, its metadata will be unknown (null values).
|
|
value:
|
|
data:
|
|
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: []
|
|
metadata:
|
|
lastSeenAt: null
|
|
platform: null
|
|
updateAvailable: null
|
|
version: null
|
|
metadata: {}
|
|
put:
|
|
summary: Edit host
|
|
description: |
|
|
Token scope required: `hosts:update`
|
|
|
|
:::caution
|
|
|
|
Any properties not provided in the request will be reset to their default values.
|
|
|
|
:::
|
|
|
|
### Request
|
|
operationId: hostEdit
|
|
tags:
|
|
- hosts
|
|
parameters:
|
|
- name: hostID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
staticAddresses:
|
|
description: List of static IPv4:port addresses. At least one is required if `isLighthouse` is `true`.
|
|
type: string
|
|
format: ipv4:port
|
|
example:
|
|
- 84.123.10.1:4242
|
|
default: []
|
|
listenPort:
|
|
description: 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.
|
|
format: integer
|
|
minimum: 0
|
|
maximum: 65535
|
|
default: 0
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Host'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
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: []
|
|
metadata:
|
|
lastSeenAt: '2023-04-05T17:19:42Z'
|
|
platform: dnclient
|
|
updateAvailable: false
|
|
version: 0.1.9
|
|
metadata: {}
|
|
delete:
|
|
summary: Delete host
|
|
description: |
|
|
Token scope required: `hosts:delete`
|
|
|
|
### Request
|
|
operationId: hostDelete
|
|
tags:
|
|
- hosts
|
|
parameters:
|
|
- name: hostID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
metadata:
|
|
type: object
|
|
/v1/hosts/{hostID}/block:
|
|
post:
|
|
summary: Block host
|
|
description: |
|
|
Prevent a host from being able to interact with other nodes on your network. See https://www.defined.net/blog/blocklisting/ for more details.
|
|
|
|
To unblock, re-enroll the host.
|
|
|
|
Token scope required: `hosts:block`
|
|
|
|
### Request
|
|
operationId: hostBlock
|
|
tags:
|
|
- hosts
|
|
parameters:
|
|
- name: hostID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
host:
|
|
$ref: '#/components/schemas/Host'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
host:
|
|
createdAt: '2023-01-25T18:15:27Z'
|
|
id: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
ipAddress: 100.100.0.29
|
|
isBlocked: true
|
|
isLighthouse: false
|
|
isRelay: false
|
|
listenPort: 0
|
|
name: Host 1
|
|
networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
|
|
staticAddresses: []
|
|
metadata:
|
|
lastSeenAt: '2023-04-05T17:19:42Z'
|
|
platform: dnclient
|
|
updateAvailable: false
|
|
version: 0.1.9
|
|
metadata: {}
|
|
/v1/hosts/{hostID}/enrollment-code:
|
|
post:
|
|
summary: Create enrollment code
|
|
description: |
|
|
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.
|
|
|
|
Token scope required: `hosts:enroll`
|
|
|
|
### Request
|
|
operationId: hostEnrollCodeCreate
|
|
tags:
|
|
- hosts
|
|
parameters:
|
|
- name: hostID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: host-24NVITKMNU3CYCEDNFWKAOBX7I
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
enrollmentCode:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: Secret code to be used in `dnclient enroll` to allow the host/lighthouse/relay to join your Managed Nebula network.
|
|
lifetimeSeconds:
|
|
type: integer
|
|
format: int64
|
|
description: The number of seconds the code is valid after being issued.
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
code: H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU
|
|
lifetimeSeconds: 86400
|
|
metadata: {}
|
|
/v1/host-and-enrollment-code:
|
|
post:
|
|
summary: Create host & enrollment code
|
|
description: |
|
|
Token scopes required: `hosts:create`, `hosts:enroll`
|
|
|
|
### Request
|
|
operationId: hostAndEnrollCodeCreate
|
|
tags:
|
|
- hosts
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- name
|
|
- networkID
|
|
properties:
|
|
name:
|
|
description: Name of the new host
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 255
|
|
example: My new host
|
|
networkID:
|
|
description: ID of your network
|
|
type: string
|
|
example: network-KAOWMXZHZWCVMGGFKM22XEGYLE
|
|
roleID:
|
|
description: ID of the role you want to assign
|
|
type: string
|
|
nullable: true
|
|
example: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
|
|
ipAddress:
|
|
description: 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.
|
|
type: string
|
|
format: ipv4
|
|
example: 100.100.0.29
|
|
staticAddresses:
|
|
description: List of static IPv4:port addresses. At least one is required if `isLighthouse` is `true`.
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: ipv4:port
|
|
example:
|
|
- 84.123.10.1:4242
|
|
default: []
|
|
listenPort:
|
|
description: 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.
|
|
format: integer
|
|
minimum: 0
|
|
maximum: 65535
|
|
default: 0
|
|
isLighthouse:
|
|
description: Set to true to create a new lighthouse. A Lighthouse cannot also be relay.
|
|
format: boolean
|
|
isRelay:
|
|
description: Set to true to create a new relay. A relay cannot also be a lighthouse.
|
|
format: boolean
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
required:
|
|
- host
|
|
properties:
|
|
host:
|
|
$ref: '#/components/schemas/Host'
|
|
enrollmentCode:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
lifetimeSeconds:
|
|
type: integer
|
|
format: int64
|
|
metadata:
|
|
type: object
|
|
example:
|
|
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: []
|
|
metadata:
|
|
lastSeenAt: '2023-04-05T17:19:42Z'
|
|
platform: dnclient
|
|
updateAvailable: false
|
|
version: 0.1.9
|
|
enrollmentCode:
|
|
code: H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU
|
|
lifetimeSeconds: 86400
|
|
metadata: {}
|
|
'400':
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- errors
|
|
properties:
|
|
errors:
|
|
$ref: '#/components/schemas/Errors'
|
|
examples:
|
|
existingHostName:
|
|
summary: A host already exists with the name.
|
|
value:
|
|
errors:
|
|
- code: ERR_DUPLICATE_VALUE
|
|
message: value already exists
|
|
path: name
|
|
cannotFindNetwork:
|
|
summary: Cannot find the supplied networkID.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_REFERENCE
|
|
message: referenced value is invalid (perhaps it does not exist?)
|
|
path: networkID
|
|
duplicateIpAddress:
|
|
summary: A host with the ipAddress supplied already exists.
|
|
value:
|
|
errors:
|
|
- code: ERR_DUPLICATE_VALUE
|
|
message: value already exists
|
|
path: ipAddress
|
|
cannotFindRole:
|
|
summary: Cannot find the supplied roleID.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_REFERENCE
|
|
message: referenced value is invalid (perhaps it does not exist?)
|
|
path: roleID
|
|
lighthouseXorRelay:
|
|
summary: A host may be a lighthouse OR a relay, but not both.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: lighthouse hosts must not also be relay hosts
|
|
lighthouseNeedsStaticIP:
|
|
summary: A lighthouse requires at least one static IP address.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: lighthouse hosts must have at least one static ip address
|
|
path: staticAddresses
|
|
lighthouseNeedsStaticPort:
|
|
summary: A lighthouse requires a static listen port, like `4242`.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: lighthouse hosts must specify a static listen port
|
|
path: listenPort
|
|
relayNeedsStaticPort:
|
|
summary: A relay requires a static listen port, like `4242`.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: relay hosts must specify a static listen port
|
|
path: listenPort
|
|
/v1/roles:
|
|
post:
|
|
summary: Create role
|
|
description: |
|
|
Create a new role.
|
|
|
|
Token scope required: `roles:create`
|
|
|
|
### Request
|
|
operationId: roleCreate
|
|
tags:
|
|
- roles
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
description: Name of the new role
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 50
|
|
example: My new role
|
|
description:
|
|
description: Optional description
|
|
type: string
|
|
maxLength: 255
|
|
firewallRules:
|
|
description: Incoming firewall rules
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FirewallRule'
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Role'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
name: My new role
|
|
description: ''
|
|
createdAt: '2023-02-15T13:59:09Z'
|
|
modifiedAt: '2023-02-15T13:59:09Z'
|
|
firewallRules:
|
|
- protocol: TCP
|
|
description: allow SSH access
|
|
allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
|
|
portRange:
|
|
from: 22
|
|
to: 22
|
|
metadata: {}
|
|
'400':
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- errors
|
|
properties:
|
|
errors:
|
|
$ref: '#/components/schemas/Errors'
|
|
examples:
|
|
missingName:
|
|
summary: <code>name</code> not specified.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE_LENGTH
|
|
message: must have a length between 1 and 50
|
|
path: name
|
|
duplicateName:
|
|
summary: A role with the name already exists.
|
|
value:
|
|
errors:
|
|
- code: ERR_DUPLICATE_VALUE
|
|
message: value already exists
|
|
path: name
|
|
protocol:
|
|
summary: Invalid <code>protocol</code> value.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: 'must be a valid protocol: ANY, TCP, UDP, ICMP'
|
|
path: firewallRules[0].protocol
|
|
portRangeMissing:
|
|
summary: Invalid/missing <code>from</code> and <code>to</code> values.
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: must be between 1 and 65535
|
|
path: firewallRules[0].portRange.from
|
|
- code: ERR_INVALID_VALUE
|
|
message: must be between 1 and 65535
|
|
path: firewallRules[0].portRange.to
|
|
portRangeOrder:
|
|
summary: <code>From</code> cannot be greater than <code>to</code>
|
|
value:
|
|
errors:
|
|
- code: ERR_INVALID_VALUE
|
|
message: from must be less than or equal to to
|
|
path: firewallRules[0].portRange
|
|
get:
|
|
summary: List roles
|
|
description: |
|
|
Get a paginated list of roles.
|
|
|
|
Token scope required: `roles:list`
|
|
|
|
### Request
|
|
operationId: rolesList
|
|
tags:
|
|
- roles
|
|
parameters:
|
|
- $ref: '#/components/parameters/includeCounts'
|
|
- $ref: '#/components/parameters/cursor'
|
|
- $ref: '#/components/parameters/pageSize'
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Role'
|
|
metadata:
|
|
$ref: '#/components/schemas/PaginationMetadata'
|
|
examples:
|
|
noParams:
|
|
summary: When <code>includeCounts</code> parameter is not set to true
|
|
value:
|
|
data:
|
|
- id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
name: My new role
|
|
description: ''
|
|
createdAt: '2023-02-15T13:59:09Z'
|
|
modifiedAt: '2023-02-15T13:59:09Z'
|
|
firewallRules:
|
|
- protocol: TCP
|
|
description: allow SSH access
|
|
allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
|
|
portRange:
|
|
from: 22
|
|
to: 22
|
|
metadata:
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
includeCounts:
|
|
summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
|
|
value:
|
|
data:
|
|
- id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
name: My new role
|
|
description: ''
|
|
createdAt: '2023-02-15T13:59:09Z'
|
|
modifiedAt: '2023-02-15T13:59:09Z'
|
|
firewallRules:
|
|
- protocol: TCP
|
|
description: allow SSH access
|
|
allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
|
|
portRange:
|
|
from: 22
|
|
to: 22
|
|
metadata:
|
|
totalCount: 500
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
page:
|
|
count: 1
|
|
start: 5
|
|
/v1/roles/{roleID}:
|
|
get:
|
|
summary: Get role
|
|
description: |
|
|
Fetch information about a particular role.
|
|
|
|
Token scope required: `roles:read`
|
|
|
|
### Request
|
|
operationId: roleGet
|
|
tags:
|
|
- roles
|
|
parameters:
|
|
- name: roleID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Role'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
name: My new role
|
|
description: ''
|
|
createdAt: '2023-02-15T13:59:09Z'
|
|
modifiedAt: '2023-02-15T13:59:09Z'
|
|
firewallRules:
|
|
- protocol: TCP
|
|
description: allow SSH access
|
|
allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
|
|
portRange:
|
|
from: 22
|
|
to: 22
|
|
metadata: {}
|
|
put:
|
|
summary: Edit role
|
|
description: |
|
|
Token scope required: `roles:update`
|
|
|
|
:::caution
|
|
|
|
Any properties not provided in the request will be reset to their default values. If only changing one firewall rule, be sure to include the others as well, otherwise they will be removed.
|
|
|
|
:::
|
|
|
|
### Request
|
|
operationId: roleEdit
|
|
tags:
|
|
- roles
|
|
parameters:
|
|
- name: roleID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
description:
|
|
type: string
|
|
maxLength: 255
|
|
firewallRules:
|
|
description: Incoming firewall rules. Will replace existing list of rules.
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FirewallRule'
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Role'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
name: My new role
|
|
description: ''
|
|
createdAt: '2023-02-15T13:59:09Z'
|
|
modifiedAt: '2023-02-15T13:59:09Z'
|
|
firewallRules:
|
|
- protocol: TCP
|
|
description: allow SSH access
|
|
allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
|
|
portRange:
|
|
from: 22
|
|
to: 22
|
|
metadata: {}
|
|
delete:
|
|
summary: Delete role
|
|
description: |
|
|
Token scope required: `roles:delete`
|
|
|
|
### Request
|
|
operationId: roleDelete
|
|
tags:
|
|
- roles
|
|
parameters:
|
|
- name: roleID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
metadata:
|
|
type: object
|
|
/v1/networks:
|
|
get:
|
|
summary: List networks
|
|
description: |
|
|
Get a paginated list of networks.
|
|
|
|
:::note
|
|
|
|
Currently, there is a limit of one network per Defined Networking account.
|
|
|
|
:::
|
|
|
|
Token scope required: `networks:list`
|
|
|
|
### Request
|
|
operationId: networksList
|
|
tags:
|
|
- networks
|
|
parameters:
|
|
- $ref: '#/components/parameters/includeCounts'
|
|
- $ref: '#/components/parameters/cursor'
|
|
- $ref: '#/components/parameters/pageSize'
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Network'
|
|
metadata:
|
|
$ref: '#/components/schemas/PaginationMetadata'
|
|
examples:
|
|
noParams:
|
|
summary: When <code>includeCounts</code> parameter is not set to true
|
|
value:
|
|
data:
|
|
- cidr: 100.100.0.0/22
|
|
id: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
signingCAID: ca-TRJSVAAAPJXTOICJMG2KZBKQEE
|
|
name: Network1
|
|
lighthousesAsRelays: false
|
|
createdAt: '2023-02-14T20:34:59Z'
|
|
metadata:
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
includeCounts:
|
|
summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
|
|
value:
|
|
data:
|
|
- cidr: 100.100.0.0/22
|
|
id: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
signingCAID: ca-TRJSVAAAPJXTOICJMG2KZBKQEE
|
|
name: Network1
|
|
lighthousesAsRelays: false
|
|
createdAt: '2023-02-14T20:34:59Z'
|
|
metadata:
|
|
totalCount: 500
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
page:
|
|
count: 1
|
|
start: 5
|
|
/v1/networks/{networkID}:
|
|
get:
|
|
summary: Get network
|
|
description: |
|
|
Fetch information about a particular network.
|
|
|
|
Token scope required: `networks:read`
|
|
|
|
### Request
|
|
operationId: networkGet
|
|
tags:
|
|
- networks
|
|
parameters:
|
|
- name: networkID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Network'
|
|
metadata:
|
|
type: object
|
|
example:
|
|
data:
|
|
cidr: 100.100.0.0/22
|
|
id: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
signingCAID: ca-TRJSVAAAPJXTOICJMG2KZBKQEE
|
|
name: Network1
|
|
lighthousesAsRelays: false
|
|
createdAt: '2023-02-14T20:34:59Z'
|
|
metadata: {}
|
|
/v1/audit-logs:
|
|
get:
|
|
summary: List audit logs
|
|
description: |
|
|
Get a paginated list of audit logs.
|
|
|
|
Token scope required: `audit-logs:list`
|
|
|
|
### Request
|
|
operationId: auditLogsList
|
|
tags:
|
|
- auditLogs
|
|
parameters:
|
|
- $ref: '#/components/parameters/includeCounts'
|
|
- $ref: '#/components/parameters/cursor'
|
|
- $ref: '#/components/parameters/pageSize'
|
|
- $ref: '#/components/parameters/filter-targetID'
|
|
- $ref: '#/components/parameters/filter-targetType'
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/AuditLog'
|
|
metadata:
|
|
$ref: '#/components/schemas/PaginationMetadata'
|
|
examples:
|
|
noParams:
|
|
summary: When <code>includeCounts</code> parameter is not set to true
|
|
value:
|
|
data:
|
|
- id: log-F3TTIDMKZH5XFH37RTRLIP3TOA
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
timestamp: '2023-02-15T13:59:09.828868Z'
|
|
actor:
|
|
id: dnkey-DXALSPQONG7H45QZAVTPRDMAPU
|
|
name: example api key
|
|
type: apiKey
|
|
target:
|
|
id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
type: role
|
|
event:
|
|
type: CREATED
|
|
before: null
|
|
after:
|
|
name: My New Role
|
|
description: ''
|
|
firewallRules: null
|
|
metadata:
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
includeCounts:
|
|
summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
|
|
value:
|
|
data:
|
|
- id: log-F3TTIDMKZH5XFH37RTRLIP3TOA
|
|
organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
|
|
timestamp: '2023-02-15T13:59:09.828868Z'
|
|
actor:
|
|
id: dnkey-DXALSPQONG7H45QZAVTPRDMAPU
|
|
name: example api key
|
|
type: apiKey
|
|
target:
|
|
id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
|
|
type: role
|
|
event:
|
|
type: CREATED
|
|
before: null
|
|
after:
|
|
name: My New Role
|
|
description: ''
|
|
firewallRules: null
|
|
metadata:
|
|
totalCount: 500
|
|
hasNextPage: true
|
|
hasPrevPage: true
|
|
prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
|
|
nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
|
|
page:
|
|
count: 1
|
|
start: 5
|
|
/v1/downloads:
|
|
get:
|
|
summary: List software downloads
|
|
description: |
|
|
Get a list of recently released software download links and basic info.
|
|
|
|
This endpoint is unauthenticated.
|
|
|
|
### Request
|
|
operationId: downloadsList
|
|
tags:
|
|
- downloads
|
|
responses:
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/Downloads'
|
|
examples:
|
|
Listing:
|
|
summary: An example downloads listing
|
|
value:
|
|
data:
|
|
dnclient:
|
|
0.1.5:
|
|
linux-amd64: https://dl.defined.net/aa96f50d/v0.1.5/linux/amd64/dnclient
|
|
linux-arm64: https://dl.defined.net/aa96f50d/v0.1.5/linux/arm64/dnclient
|
|
linux-armv7: https://dl.defined.net/aa96f50d/v0.1.5/linux/arm-7/dnclient
|
|
linux-mips-softfloat: https://dl.defined.net/aa96f50d/v0.1.5/linux/mips-softfloat/dnclient
|
|
macos-universal: https://dl.defined.net/aa96f50d/v0.1.5/macos/dnclient
|
|
macos-universal-dmg: https://dl.defined.net/aa96f50d/v0.1.5/macos/dnclient.dmg
|
|
windows-amd64: https://dl.defined.net/aa96f50d/v0.1.5/windows/amd64/DNClient.msi
|
|
windows-arm64: https://dl.defined.net/aa96f50d/v0.1.5/windows/arm64/DNClient.msi
|
|
0.1.6:
|
|
linux-amd64: https://dl.defined.net/02c6d0f9/v0.1.6/linux/amd64/dnclient
|
|
linux-arm64: https://dl.defined.net/02c6d0f9/v0.1.6/linux/arm64/dnclient
|
|
linux-armv7: https://dl.defined.net/02c6d0f9/v0.1.6/linux/arm-7/dnclient
|
|
linux-mips-softfloat: https://dl.defined.net/02c6d0f9/v0.1.6/linux/mips-softfloat/dnclient
|
|
macos-universal: https://dl.defined.net/02c6d0f9/v0.1.6/macos/dnclient
|
|
macos-universal-dmg: https://dl.defined.net/02c6d0f9/v0.1.6/macos/dnclient.dmg
|
|
windows-amd64: https://dl.defined.net/02c6d0f9/v0.1.6/windows/amd64/DNClient.msi
|
|
windows-arm64: https://dl.defined.net/02c6d0f9/v0.1.6/windows/arm64/DNClient.msi
|
|
0.1.7:
|
|
linux-amd64: https://dl.defined.net/0ef94adc/v0.1.7/linux/amd64/dnclient
|
|
linux-arm64: https://dl.defined.net/0ef94adc/v0.1.7/linux/arm64/dnclient
|
|
linux-armv7: https://dl.defined.net/0ef94adc/v0.1.7/linux/arm-7/dnclient
|
|
linux-mips-softfloat: https://dl.defined.net/0ef94adc/v0.1.7/linux/mips-softfloat/dnclient
|
|
macos-universal: https://dl.defined.net/0ef94adc/v0.1.7/macos/dnclient
|
|
macos-universal-dmg: https://dl.defined.net/0ef94adc/v0.1.7/macos/dnclient.dmg
|
|
windows-amd64: https://dl.defined.net/0ef94adc/v0.1.7/windows/amd64/DNClient.msi
|
|
windows-arm64: https://dl.defined.net/0ef94adc/v0.1.7/windows/arm64/DNClient.msi
|
|
0.1.8:
|
|
freebsd-amd64: https://dl.defined.net/e16d2e9f/v0.1.8/freebsd/amd64/dnclient
|
|
freebsd-arm64: https://dl.defined.net/e16d2e9f/v0.1.8/freebsd/arm64/dnclient
|
|
linux-386: https://dl.defined.net/e16d2e9f/v0.1.8/linux/386/dnclient
|
|
linux-amd64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/amd64/dnclient
|
|
linux-arm64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm64/dnclient
|
|
linux-armv5: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm-5/dnclient
|
|
linux-armv6: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm-6/dnclient
|
|
linux-armv7: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm-7/dnclient
|
|
linux-mips: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips/dnclient
|
|
linux-mips-softfloat: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips-softfloat/dnclient
|
|
linux-mips64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips64/dnclient
|
|
linux-mips64le: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips64le/dnclient
|
|
linux-mipsle: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mipsle/dnclient
|
|
linux-ppc64le: https://dl.defined.net/e16d2e9f/v0.1.8/linux/ppc64le/dnclient
|
|
linux-riscv64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/riscv64/dnclient
|
|
macos-universal: https://dl.defined.net/e16d2e9f/v0.1.8/macos/dnclient
|
|
macos-universal-dmg: https://dl.defined.net/e16d2e9f/v0.1.8/macos/dnclient.dmg
|
|
windows-amd64: https://dl.defined.net/e16d2e9f/v0.1.8/windows/amd64/DNClient.msi
|
|
windows-arm64: https://dl.defined.net/e16d2e9f/v0.1.8/windows/arm64/DNClient.msi
|
|
0.1.9:
|
|
freebsd-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/amd64/dnclient,
|
|
freebsd-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/arm64/dnclient,
|
|
linux-386: https://dl.defined.net/02c6d0f9/v0.1.9/linux/386/dnclient,
|
|
linux-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/amd64/dnclient,
|
|
linux-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm64/dnclient,
|
|
linux-armv5: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-5/dnclient,
|
|
linux-armv6: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-6/dnclient,
|
|
linux-armv7: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-7/dnclient,
|
|
linux-mips: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips/dnclient,
|
|
linux-mips-softfloat: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips-softfloat/dnclient,
|
|
linux-mips64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64/dnclient,
|
|
linux-mips64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64le/dnclient,
|
|
linux-mipsle: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mipsle/dnclient,
|
|
linux-ppc64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/ppc64le/dnclient,
|
|
linux-riscv64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/riscv64/dnclient,
|
|
macos-universal: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient,
|
|
macos-universal-dmg: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient.dmg,
|
|
windows-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/amd64/DNClient.msi,
|
|
windows-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/arm64/DNClient.msi
|
|
latest:
|
|
freebsd-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/amd64/dnclient,
|
|
freebsd-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/arm64/dnclient,
|
|
linux-386: https://dl.defined.net/02c6d0f9/v0.1.9/linux/386/dnclient,
|
|
linux-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/amd64/dnclient,
|
|
linux-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm64/dnclient,
|
|
linux-armv5: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-5/dnclient,
|
|
linux-armv6: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-6/dnclient,
|
|
linux-armv7: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-7/dnclient,
|
|
linux-mips: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips/dnclient,
|
|
linux-mips-softfloat: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips-softfloat/dnclient,
|
|
linux-mips64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64/dnclient,
|
|
linux-mips64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64le/dnclient,
|
|
linux-mipsle: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mipsle/dnclient,
|
|
linux-ppc64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/ppc64le/dnclient,
|
|
linux-riscv64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/riscv64/dnclient,
|
|
macos-universal: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient,
|
|
macos-universal-dmg: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient.dmg,
|
|
windows-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/amd64/DNClient.msi,
|
|
windows-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/arm64/DNClient.msi
|
|
mobile:
|
|
android: https://play.google.com/store/apps/details?id=net.defined.mobile_nebula
|
|
ios: https://apps.apple.com/us/app/mobile-nebula/id1509587936
|
|
versionInfo:
|
|
dnclient:
|
|
0.1.5:
|
|
latest: false
|
|
releaseDate: '2022-07-13'
|
|
0.1.6:
|
|
latest: false
|
|
releaseDate: '2022-12-15'
|
|
0.1.7:
|
|
latest: false
|
|
releaseDate: '2022-12-16'
|
|
0.1.8:
|
|
latest: false
|
|
releaseDate: '2022-12-20'
|
|
0.1.9:
|
|
latest: true
|
|
releaseDate: '2023-03-15'
|
|
latest:
|
|
dnclient: 0.1.9
|
|
mobile: 0.2.0
|
|
components:
|
|
securitySchemes:
|
|
ApiToken:
|
|
description: |
|
|
Get an api key from https://admin.defined.net/settings/api-keys with the permission scopes required.
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: dnkey
|
|
parameters:
|
|
includeCounts:
|
|
name: includeCounts
|
|
in: query
|
|
description: If true, return count of total records and current page start and count in metadata
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
cursor:
|
|
name: cursor
|
|
in: query
|
|
description: Cursor value at which to start the results, provided in `nextCursor` or `prevCursor` of a prior request
|
|
example: bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19
|
|
schema:
|
|
type: string
|
|
pageSize:
|
|
name: pageSize
|
|
in: query
|
|
description: Number of records to return in each page
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
default: 25
|
|
maximum: 500
|
|
filter-isBlocked:
|
|
name: filter.isBlocked
|
|
in: query
|
|
description: Return only hosts that are blocked if true, unblocked if false
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
filter-isLighthouse:
|
|
name: filter.isLighthouse
|
|
in: query
|
|
description: Return only lighthouses if true, non-lighthouses if false
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
filter-isRelay:
|
|
name: filter.isRelay
|
|
in: query
|
|
description: Return only relays if true, non-relays if false
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
filter-metadata-lastSeenAt:
|
|
name: filter.metadata.lastSeenAt
|
|
in: query
|
|
description: When "null", returns hosts that have never communicated with the Defined Networking service.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- 'null'
|
|
filter-metadata-platform:
|
|
name: filter.metadata.platform
|
|
in: query
|
|
description: Return only hosts matching the specified client platform
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- mobile
|
|
- dnclient
|
|
- 'null'
|
|
filter-metadata-updateAvailable:
|
|
name: filter.metadata.updateAvailable
|
|
in: query
|
|
description: Return only hosts that have updates available when true, or up-to-date hosts when false
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
filter-targetID:
|
|
name: filter.targetID
|
|
in: query
|
|
description: Return only audit logs for the specified target
|
|
required: false
|
|
schema:
|
|
type: string
|
|
filter-targetType:
|
|
name: filter.targetType
|
|
in: query
|
|
description: Return only audit logs matching the specified target type
|
|
required: false
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- apiKey
|
|
- host
|
|
- network
|
|
- role
|
|
- user
|
|
- ca
|
|
- oidcProvider
|
|
schemas:
|
|
Host:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
organizationID:
|
|
type: string
|
|
networkID:
|
|
type: string
|
|
roleID:
|
|
type: string
|
|
nullable: true
|
|
name:
|
|
type: string
|
|
ipAddress:
|
|
type: string
|
|
format: ipv4
|
|
staticAddresses:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: ipv4:port
|
|
listenPort:
|
|
type: integer
|
|
format: int64
|
|
description: Will be zero if a regular host
|
|
isLighthouse:
|
|
type: boolean
|
|
default: false
|
|
isRelay:
|
|
type: boolean
|
|
default: false
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
isBlocked:
|
|
type: boolean
|
|
default: false
|
|
metadata:
|
|
type: object
|
|
properties:
|
|
lastSeenAt:
|
|
type: string
|
|
nullable: true
|
|
version:
|
|
type: string
|
|
nullable: true
|
|
platform:
|
|
type: string
|
|
nullable: true
|
|
enum:
|
|
- dnclient
|
|
- mobile
|
|
- null
|
|
updateAvailable:
|
|
type: boolean
|
|
nullable: true
|
|
PaginationMetadata:
|
|
type: object
|
|
properties:
|
|
totalCount:
|
|
type: integer
|
|
description: The total number of resources existing in the account
|
|
hasNextPage:
|
|
type: boolean
|
|
description: Is there a page of data that can be fetched using the `nextCursor`?
|
|
hasPrevPage:
|
|
type: boolean
|
|
description: Is there a page of data that can be fetched using the `prevCursor`?
|
|
nextCursor:
|
|
type: string
|
|
description: An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
|
|
prevCursor:
|
|
type: string
|
|
description: An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
|
|
page:
|
|
type: object
|
|
required:
|
|
- count
|
|
- start
|
|
properties:
|
|
count:
|
|
type: integer
|
|
description: The number of results returned in the response.
|
|
start:
|
|
type: integer
|
|
description: The zero-based index of the first result within the overall list. For example, the first page will have a `start` of `0`. If 25 results are fetched, and the `nextCursor` used to fetch a new page of results, the second request's `start` will be `25`.
|
|
Error:
|
|
type: object
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: A static name for the error type
|
|
message:
|
|
type: string
|
|
description: A short human readable description of the error
|
|
path:
|
|
type: string
|
|
nullable: true
|
|
description: Describes the variable missing or malformed
|
|
Errors:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Error'
|
|
FirewallRule:
|
|
type: object
|
|
required:
|
|
- protocol
|
|
properties:
|
|
protocol:
|
|
type: string
|
|
enum:
|
|
- ANY
|
|
- TCP
|
|
- UDP
|
|
- ICMP
|
|
description:
|
|
type: string
|
|
maxLength: 255
|
|
allowedRoleID:
|
|
type: string
|
|
description: Role ID to allow with this firewall rule. If not specified, all roles are included.
|
|
portRange:
|
|
type: object
|
|
required:
|
|
- from
|
|
- to
|
|
description: Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
|
|
properties:
|
|
from:
|
|
type: integer
|
|
description: First port number included in range.
|
|
minimum: 1
|
|
maximum: 65535
|
|
to:
|
|
type: integer
|
|
description: Last port number included in range. Must be greater than `from` port.
|
|
minimum: 1
|
|
maximum: 65535
|
|
Role:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description:
|
|
type: string
|
|
firewallRules:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FirewallRule'
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
modifiedAt:
|
|
type: string
|
|
format: date-time
|
|
Network:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
cidr:
|
|
type: string
|
|
format: ipv4/cidr
|
|
organizationID:
|
|
type: string
|
|
signingCAID:
|
|
description: The ID of the Certificate Authority being used.
|
|
type: string
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
name:
|
|
type: string
|
|
default: Network1
|
|
lighthousesAsRelays:
|
|
type: boolean
|
|
Actor-APIKey:
|
|
title: apiKey
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: An API key which used to perform the action.
|
|
enum:
|
|
- apiKey
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
nullable: true
|
|
Actor-Host:
|
|
title: host
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: A host. Used for example when hosts are enrolled.
|
|
enum:
|
|
- host
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
nullable: true
|
|
Actor-OIDCUser:
|
|
title: oidcUser
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: A user who logged in using SSO.
|
|
enum:
|
|
- oidcUser
|
|
email:
|
|
type: string
|
|
format: email
|
|
issuer:
|
|
type: string
|
|
subject:
|
|
type: string
|
|
Actor-Support:
|
|
title: support
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: A member of Defined Networking support staff.
|
|
enum:
|
|
- support
|
|
Actor-System:
|
|
title: system
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: System actor, used for events such as creation or rotation of Certificate Authorities.
|
|
enum:
|
|
- system
|
|
Actor-User:
|
|
title: user
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: A logged-in user.
|
|
enum:
|
|
- user
|
|
id:
|
|
type: string
|
|
email:
|
|
type: string
|
|
format: email
|
|
Actor:
|
|
description: The entity performing the action which caused a change.
|
|
oneOf:
|
|
- $ref: '#/components/schemas/Actor-APIKey'
|
|
- $ref: '#/components/schemas/Actor-Host'
|
|
- $ref: '#/components/schemas/Actor-OIDCUser'
|
|
- $ref: '#/components/schemas/Actor-Support'
|
|
- $ref: '#/components/schemas/Actor-System'
|
|
- $ref: '#/components/schemas/Actor-User'
|
|
Target:
|
|
type: object
|
|
description: The entity being acted upon.
|
|
properties:
|
|
id:
|
|
type: string
|
|
type:
|
|
type: string
|
|
enum:
|
|
- apiKey
|
|
- ca
|
|
- host
|
|
- network
|
|
- oidcProvider
|
|
- role
|
|
- user
|
|
Event:
|
|
type: object
|
|
description: Information about what happened, including relevant values before & after the change.
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: The type of event that occurred.
|
|
enum:
|
|
- CREATED
|
|
- UPDATED
|
|
- DELETED
|
|
- DELETED_TOTP
|
|
- CREATED_TOTP
|
|
- SUCCEEDED_AUTH
|
|
- FAILED_AUTH
|
|
- ENROLLED
|
|
- RENEWED
|
|
- CREATED_ENROLL_CODE
|
|
- SET_NETWORK_CA
|
|
- BLOCKED_HOST
|
|
- UNBLOCKED_HOST
|
|
- SET_OVERRIDES
|
|
before:
|
|
description: The state of the target before the change was made. The shape depends on the target and event type. Can also be a string or null (e.g. target was created).
|
|
type: object
|
|
nullable: true
|
|
additionalProperties: {}
|
|
after:
|
|
description: The state of the target before the change was made. The shape depends on the target and event type. Can also be a string or null (e.g. target was deleted).
|
|
type: object
|
|
nullable: true
|
|
additionalProperties: {}
|
|
AuditLog:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
organizationID:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
actor:
|
|
$ref: '#/components/schemas/Actor'
|
|
target:
|
|
$ref: '#/components/schemas/Target'
|
|
event:
|
|
$ref: '#/components/schemas/Event'
|
|
DownloadsDNClientLinks:
|
|
type: object
|
|
description: Download links for a given DNClient version
|
|
properties:
|
|
linux-amd64:
|
|
type: string
|
|
linux-arm64:
|
|
type: string
|
|
macos-universal:
|
|
type: string
|
|
macos-universal-dmg:
|
|
type: string
|
|
windows-amd64:
|
|
type: string
|
|
windows-arm64:
|
|
type: string
|
|
additionalProperties:
|
|
x-additionalPropertiesName: os-platform
|
|
type: string
|
|
Downloads:
|
|
type: object
|
|
properties:
|
|
dnclient:
|
|
type: object
|
|
properties:
|
|
latest:
|
|
description: Download links for the latest DNClient version
|
|
$ref: '#/components/schemas/DownloadsDNClientLinks'
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/DownloadsDNClientLinks'
|
|
mobile:
|
|
type: object
|
|
properties:
|
|
android:
|
|
description: Mobile Nebula download URL for Android devices.
|
|
type: string
|
|
ios:
|
|
description: Mobile Nebula download URL for iOS devices.
|
|
type: string
|
|
versionInfo:
|
|
type: object
|
|
properties:
|
|
dnclient:
|
|
description: Information about available DNClient releases
|
|
type: object
|
|
additionalProperties:
|
|
description: Information about a given DNClient release
|
|
type: object
|
|
properties:
|
|
releaseDate:
|
|
type: string
|
|
latest:
|
|
type: boolean
|
|
latest:
|
|
description: The latest version for each software download.
|
|
type: object
|
|
properties:
|
|
dnclient:
|
|
description: The latest version of DNClient.
|
|
type: string
|
|
mobile:
|
|
description: The latest version of Mobile Nebula.
|
|
type: string
|