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