openapi: 3.1.0
info:
  title: 'Forward Networks: Jump Servers API'
  description: Configure jump servers to assist in reaching network devices
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: ${apiVersion}
servers:
  - url: /
security:
  - api_token: []
tags:
  - name: Jump Servers
    description: Configure jump servers to assist in reaching network devices
paths:
  /api/networks/{networkId}/jumpServers:
    get:
      tags:
        - Jump Servers
      summary: Lists a network’s jump servers
      description: Substitutes a system-generated identifier for each sensitive `password` and `sshKey`.
      operationId: getJumpServersUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredJumpServer'
    post:
      tags:
        - Jump Servers
      summary: Creates a jump server
      operationId: createJumpServerUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewJumpServer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JumpServer'
  /api/networks/{networkId}/jumpServers/{jumpServerId}:
    delete:
      tags:
        - Jump Servers
      summary: Deletes a jump server
      operationId: deleteJumpServerUsingDELETE
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: jumpServerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
    patch:
      tags:
        - Jump Servers
      summary: Updates a jump server
      description: All JSON properties in the request body are optional. Include only the properties you wish to change.
      operationId: editJumpServerUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: jumpServerId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JumpServerUpdate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Attribution:
      type: object
      properties:
        createdById:
          type: string
          description: 'The ID of the user who created this entity, if known. *Note*: The referenced user account might no longer exist since an administrator can delete accounts.'
          examples:
            - '456'
        createdAt:
          type: string
          description: When this entity was created, if known.
          examples:
            - '2021-12-29T16:30:45.111Z'
        createdBy:
          type: string
          description: The username of the user who created this entity, if known. Absent if the user account has been deleted.
          examples:
            - me@example.com
        updatedById:
          type: string
          description: 'The ID of the user who most recently updated this entity, if known. *Note*: The referenced user account might no longer exist since an administrator can delete accounts.'
          examples:
            - '789'
        updatedAt:
          type: string
          description: When this entity was most recently updated, if known.
          examples:
            - '2024-10-27T21:44:51.345Z'
        updatedBy:
          type: string
          description: The username of the user who most recently updated this entity, if known. Absent if the user account has been deleted.
          examples:
            - you@example.com
    JumpServer:
      type: object
      required:
        - host
        - username
      properties:
        id:
          type: string
          examples:
            - 8c4a168e-c6ca-4978-bcc9-c0ec7f64a164
        host:
          type: string
          examples:
            - 10.121.7.14
        port:
          type: integer
          format: int32
          description: defaults to 22
          examples:
            - 23
        username:
          type: string
          examples:
            - admin
        password:
          type: string
          description: Either this or `sshKey` must be provided in requests. A system-generated identifier is substituted for the actual password in responses.
          examples:
            - my-s3cr3t-p4s$w0rd
        sshKey:
          type: string
          description: SSH private key for authentication. Either this or `password` must be provided in requests. Requires `supportsPortForwarding` to be true. A system-generated identifier is substituted for the actual key in responses.
          examples:
            - |-
              -----BEGIN RSA PRIVATE KEY-----
              MIIPIQIBAzCCDtoGCSqGSIb3DQEHAa...
        sshCert:
          type: string
          description: SSH user certificate for authentication. Applicable only for certificate based authentication and requires `sshKey` to be provided.
          examples:
            - ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1yc2EtY2VydC12MDFAb3BlbnNzaC5jb20AAA...
        supportsPortForwarding:
          type: boolean
          description: defaults to true
          examples:
            - false
        commandFormat:
          $ref: '#/components/schemas/JumpServerCommandFormat'
          description: applicable when supportsPortForwarding is false, defaults to UNIX
          examples:
            - CISCO_IOS
        vrf:
          type: string
          description: VRF that this jump server should use to connect to devices. Can be set only if `commandFormat` is CISCO_IOS.
          examples:
            - Management-vrf
        authenticationTimeoutSeconds:
          type: integer
          format: int32
          description: seconds to wait for the jump server authentication response. Defaults to 20.
          examples:
            - 20
    JumpServerCommandFormat:
      type: string
      enum:
        - UNIX
        - CISCO_IOS
        - JUNOS
        - PANORAMA
    JumpServerUpdate:
      type: object
      properties:
        host:
          type: string
          examples:
            - 10.121.7.14
        port:
          type: integer
          format: int32
          examples:
            - 23
        username:
          type: string
          examples:
            - admin
        password:
          type: string
          examples:
            - my-s3cr3t-p4s$w0rd
        sshKey:
          type: string
          examples:
            - |-
              -----BEGIN RSA PRIVATE KEY-----
              MIIPIQIBAzCCDtoGCSqGSIb3DQEHAa...
        sshCert:
          type: string
          examples:
            - ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1yc2EtY2VydC12MDFAb3BlbnNzaC5jb20AAA...
        supportsPortForwarding:
          type: boolean
          examples:
            - false
        commandFormat:
          $ref: '#/components/schemas/JumpServerCommandFormat'
          examples:
            - CISCO_IOS
        vrf:
          type: string
          examples:
            - Management-vrf
        authenticationTimeoutSeconds:
          type: integer
          format: int32
          examples:
            - 20
    NewJumpServer:
      type: object
      required:
        - host
        - username
      properties:
        host:
          type: string
          examples:
            - 10.121.7.14
        port:
          type: integer
          format: int32
          description: defaults to 22
          examples:
            - 23
        username:
          type: string
          examples:
            - admin
        password:
          type: string
          description: Either this or `sshKey` is required
          examples:
            - my-s3cr3t-p4s$w0rd
        sshKey:
          type: string
          description: SSH private key for authentication. Either this or `password` is required. Requires `supportsPortForwarding` to be true.
          examples:
            - |-
              -----BEGIN RSA PRIVATE KEY-----
              MIIPIQIBAzCCDtoGCSqGSIb3DQEHAa…
        sshCert:
          type: string
          description: SSH user certificate for authentication. Applicable only for certificate based authentication and requires `sshKey` to be provided.
          examples:
            - ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1yc2EtY2VydC12MDFAb3BlbnNzaC5jb20AAA…
        supportsPortForwarding:
          type: boolean
          description: defaults to true
          examples:
            - false
        commandFormat:
          $ref: '#/components/schemas/JumpServerCommandFormat'
          description: applicable when supportsPortForwarding is false, defaults to UNIX
          examples:
            - CISCO_IOS
        vrf:
          type: string
          description: VRF that this jump server should use to connect to devices. Can be set only if `commandFormat` is CISCO_IOS.
          examples:
            - Management-vrf
        authenticationTimeoutSeconds:
          type: integer
          format: int32
          description: seconds to wait for the jump server authentication response. Defaults to 20.
          examples:
            - 20
    StoredJumpServer:
      allOf:
        - $ref: '#/components/schemas/JumpServer'
        - $ref: '#/components/schemas/Attribution'
  securitySchemes:
    api_token:
      type: http
      scheme: basic
