openapi: 3.2.0
info:
  title: 'Forward: Encryptors API'
  summary: Model the devices encapsulating a network’s traffic in IPSEC tunnels
  description: |-
    An encryptor has a site connection, an optional underlay connection, one or more tunnels, and the subnets carried
    over them. It is one kind of
    [synthetic device](https://docs.fwd.app/latest/application/sources/configure-collection/synthetic-devices/), and the
    only kind with no editor in the app, so these operations are the only way to configure it. For the modeling details,
    see [Encryptor](https://docs.fwd.app/latest/application/sources/configure-collection/synthetic-devices/reference/#encryptor).

    Changes to a network’s encryptors affect future Snapshots.
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: 26.8
servers:
  - url: /api
security:
  - api_token: []
tags:
  - name: Collection Sources
    description: Specify the devices, endpoints, and other sources to collect from
  - name: Synthetic Devices
    description: Model a network’s internet connections, intranets, L2VPNs, L3VPNs, WAN circuits, and encryptors
    parent: Collection Sources
  - name: Encryptors
    description: Model the devices encapsulating a network’s traffic in IPSEC tunnels
    parent: Synthetic Devices
paths:
  /networks/{networkId}/encryptors:
    get:
      tags:
        - Encryptors
      summary: Get a network's encryptors
      operationId: getEncryptors
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptorList'
    put:
      tags:
        - Encryptors
      summary: Replace all of a network’s encryptors
      operationId: putEncryptors
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptorList'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /networks/{networkId}/encryptors/{deviceName}:
    get:
      tags:
        - Encryptors
      summary: Get an encryptor
      operationId: getEncryptor
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: deviceName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Encryptor'
    put:
      tags:
        - Encryptors
      summary: Add or replace an encryptor
      operationId: putEncryptor
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: deviceName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Encryptor'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
    patch:
      tags:
        - Encryptors
      summary: Update an encryptor
      description: |-
        All JSON properties in the request body are optional. Include only the properties you wish to
        change.
      operationId: patchEncryptor
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: deviceName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptorPatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Encryptor'
    delete:
      tags:
        - Encryptors
      summary: Remove an encryptor
      operationId: deleteEncryptor
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: deviceName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content: {}
components:
  schemas:
    Encryptor:
      type: object
      required:
        - name
        - siteConnection
        - tunnels
      properties:
        name:
          type: string
          examples:
            - encryptor
        siteConnection:
          $ref: '#/components/schemas/EncryptorConnection'
          description: A connection to a high site
        underlayConnection:
          $ref: '#/components/schemas/EncryptorConnection'
          description: A connection to the underlay network (a low site)
        tunnels:
          type: array
          items:
            $ref: '#/components/schemas/EncryptorTunnel'
          description: |-
            Tunnels to other encryptor devices. A tunnel source address is modeled as residing on this device and the
            destination addresses on another encryptor device. A source address may be reused on an encryptor. Each
            destination address must match the source address of the tunnel on another encryptor, and vice-versa
        subnets:
          type: array
          items:
            type: string
          description: |-
            Subnets to route to the high site, in addition to the source addresses of tunnels on the `siteConnection`
            gateway device
    EncryptorList:
      type: object
      required:
        - encryptors
      properties:
        encryptors:
          type: array
          items:
            $ref: '#/components/schemas/Encryptor'
    EncryptorPatch:
      type: object
      properties:
        name:
          type: string
        siteConnection:
          $ref: '#/components/schemas/EncryptorConnection'
        underlayConnection:
          $ref: '#/components/schemas/EncryptorConnection'
        tunnels:
          type: array
          items:
            $ref: '#/components/schemas/EncryptorTunnel'
          description: If specified, this list will **replace** all existing tunnels on the encryptor.
        subnets:
          type: array
          items:
            type: string
          description: If specified, this set will **replace** all existing subnets on the encryptor.
    DevicePort:
      type: object
      properties:
        device:
          type: string
        port:
          type: string
    EncryptorConnection:
      type: object
      required:
        - uplinkPort
      properties:
        uplinkPort:
          $ref: '#/components/schemas/DevicePort'
          description: The physical uplink port on the edge device.
          examples:
            - device: nyc-rtr-01
              port: eth1/1
        gatewayPort:
          $ref: '#/components/schemas/DevicePort'
          description: The virtual gateway port, if different than `uplinkPort`.
          examples:
            - device: nyc-rtr-01
              port: vlan100
        vlan:
          type: integer
          format: int32
          description: The VLAN of traffic from `uplinkPort`, if tagged.
          examples:
            - 100
        name:
          type: string
          description: |-
            An optional name for this connection, which will be used as the interface name created on the synthetic
            device that links to the physical edge port.
    EncryptorTunnel:
      type: object
      required:
        - source
        - destination
      properties:
        source:
          type: string
          description: Source IP address of an encryptor tunnel
          examples:
            - 1.1.1.1
        destination:
          type: string
          description: Destination IP address of an encryptor tunnel
          examples:
            - 2.2.2.2
  securitySchemes:
    api_token:
      type: http
      scheme: basic
