openapi: 3.1.0
info:
  title: 'Forward Networks: Credentials API'
  description: Provide network device credentials needed for network collection
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: ${apiVersion}
servers:
  - url: /api
security:
  - api_token: []
tags:
  - name: Credentials
    description: Provide network device credentials needed for network collection
paths:
  /networks/{networkId}/cli-credentials:
    get:
      tags:
        - Credentials
      summary: Lists network device CLI credentials
      description: Substitutes a system-generated identifier for each sensitive `password`.
      operationId: getCliCredentialsUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredCliCredential'
    post:
      tags:
        - Credentials
      summary: Creates a network device CLI credential
      operationId: createCliCredentialUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCliCredential'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CliCredential'
    patch:
      tags:
        - Credentials
      summary: Creates network device CLI credentials
      description: The response contains the same credentials as the request, in the same order.
      operationId: createCliCredentialsUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/NewCliCredential'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredCliCredential'
  /networks/{networkId}/cli-credentials/{credentialId}:
    get:
      tags:
        - Credentials
      summary: Gets a network device CLI credential
      description: Substitutes a system-generated identifier for the sensitive `password`.
      operationId: getCliCredentialUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredCliCredential'
    delete:
      tags:
        - Credentials
      summary: Deletes a network device CLI credential
      operationId: deleteCliCredentialUsingDELETE
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content: {}
    patch:
      tags:
        - Credentials
      summary: Updates a network device CLI credential
      description: |-
        All JSON properties in the request body are optional. Include only the properties you wish to
        change.
      operationId: patchCliCredentialUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CliCredentialUpdate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredCliCredential'
  /networks/{networkId}/http-credentials:
    get:
      tags:
        - Credentials
      summary: Lists network device HTTP credentials
      description: Substitutes a system-generated identifier for each sensitive `password`.
      operationId: getHttpCredentialsUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredHttpCredential'
    post:
      tags:
        - Credentials
      summary: Creates a network device HTTP credential
      operationId: createHttpCredentialUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewHttpCredential'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpCredential'
    patch:
      tags:
        - Credentials
      summary: Creates network device HTTP credentials
      description: The response contains the same credentials as the request, in the same order.
      operationId: createHttpCredentialsUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/NewHttpCredential'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StoredHttpCredential'
  /networks/{networkId}/http-credentials/{credentialId}:
    get:
      tags:
        - Credentials
      summary: Gets a network device HTTP credential
      description: Substitutes a system-generated identifier for the sensitive `password`.
      operationId: getHttpCredentialUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredHttpCredential'
    delete:
      tags:
        - Credentials
      summary: Deletes a network device HTTP credential
      operationId: deleteHttpCredentialUsingDELETE
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content: {}
    patch:
      tags:
        - Credentials
      summary: Updates a network device HTTP credential
      description: |-
        All JSON properties in the request body are optional. Include only the properties you wish to
        change.
      operationId: patchHttpCredentialUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpCredentialUpdate'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
components:
  schemas:
    CliCredential:
      type: object
      required:
        - type
        - name
        - password
      properties:
        id:
          type: string
          examples:
            - L-3
        type:
          $ref: '#/components/schemas/CliCredentialType'
          examples:
            - LOGIN
        name:
          type: string
          description: For display purposes in the application
          examples:
            - admin (sjc)
        username:
          type: string
          description: Required for `LOGIN` and `SHELL` types
          examples:
            - admin
        password:
          type: string
          description: A system-generated identifier is substituted for the actual password in responses.
          examples:
            - my-s3cr3t-p4s$w0rd
        privilegedModePasswordId:
          type: string
          description: |-
            Only valid for `LOGIN` type. If set, only this credential will be used on devices that require a privileged
            mode password during a connectivity test or collection. If a privileged mode password is specified both here
            and in a `ClassicDevice`, the one in the `ClassicDevice` will be used.
          examples:
            - PM-6
        privilegeLevel:
          type: integer
          format: int32
          description: |-
            Only valid for `PRIVILEGED_MODE` type. On Checkpoint devices, this is used as the TACACS privilege level, as
            in TACP-15. If absent, the highest privilege level will be used. Has no effect for other kinds of devices.
          examples:
            - 15
        autoAssociate:
          type: boolean
          description: |-
            Whether this credential can be attempted on devices not explicitly configured to use it.
            Defaults to true.
    CliCredentialUpdate:
      type: object
      properties:
        name:
          type: string
          description: For display purposes in the application
          examples:
            - admin (sjc)
        username:
          type: string
          description: for `LOGIN` and `SHELL` types
          examples:
            - admin
        password:
          type: string
          examples:
            - my-s3cr3t-p4s$w0rd
        privilegedModePasswordId:
          type: string
          description: |-
            Only valid for `LOGIN` type. If set, only this credential will be used on devices that require a privileged
            mode password during a connectivity test or collection. If a privileged mode password is specified both here
            and in a `ClassicDevice`, the one in the `ClassicDevice` will be used.
          examples:
            - 31d70f9f-a279-44ac-a621-ab3181966ad8
        privilegeLevel:
          type: integer
          format: int32
          description: |-
            Only valid for `PRIVILEGED_MODE` type. On Checkpoint devices, this is used as the TACACS privilege level, as
            in TACP-15. If absent, the highest privilege level will be used. Has no effect for other kinds of devices.
          examples:
            - 15
        autoAssociate:
          type: boolean
          description: Only supported for `LOGIN`, `PRIVILEGED_MODE`, and `SHELL` types.
    HttpCredential:
      type: object
      required:
        - type
        - name
        - password
      properties:
        id:
          type: string
          examples:
            - H-3
        type:
          $ref: '#/components/schemas/HttpCredentialType'
          examples:
            - LOGIN
        name:
          type: string
          description: For display purposes in the application
          examples:
            - admin (sjc)
        username:
          type: string
          description: Required for the `LOGIN` type
          examples:
            - admin
        password:
          type: string
          description: A system-generated identifier is substituted for the actual password in responses.
          examples:
            - my-s3cr3t-p4s$w0rd
        loginType:
          $ref: '#/components/schemas/LoginType'
          description: Required only for a credential of type `LOGIN` used by a Silver Peak Orchestrator
          examples:
            - LOCAL
        autoAssociate:
          type: boolean
          description: Defaults to true for the `LOGIN` type. Not allowed for the `API_KEY` type.
          examples:
            - false
    HttpCredentialUpdate:
      type: object
      required:
        - name
        - password
      properties:
        name:
          type: string
          description: For display purposes in the application
          examples:
            - admin (sjc)
        username:
          type: string
          description: Required for the `LOGIN` type
          examples:
            - admin
        password:
          type: string
          examples:
            - my-s3cr3t-p4s$w0rd
        loginType:
          $ref: '#/components/schemas/LoginType'
          description: Required only for a credential of type `LOGIN` used by a Silver Peak Orchestrator
          examples:
            - LOCAL
        autoAssociate:
          type: boolean
          description: Defaults to true for the `LOGIN` type. Not allowed for the `API_KEY` type.
          examples:
            - false
    NewCliCredential:
      type: object
      required:
        - type
        - name
        - password
      properties:
        type:
          $ref: '#/components/schemas/CliCredentialType'
          examples:
            - LOGIN
        name:
          type: string
          description: For display purposes in the application
          examples:
            - admin (sjc)
        username:
          type: string
          description: Required for `LOGIN` and `SHELL` types
          examples:
            - admin
        password:
          type: string
          examples:
            - my-s3cr3t-p4s$w0rd
        privilegedModePasswordId:
          type: string
          description: |-
            Only valid for `LOGIN` type. If set, only this credential will be used on devices that require a privileged
            mode password during a connectivity test or collection. If a privileged mode password is specified both here
            and in a `ClassicDevice`, the one in the `ClassicDevice` will be used.
          examples:
            - 31d70f9f-a279-44ac-a621-ab3181966ad8
        privilegeLevel:
          type: integer
          format: int32
          description: |-
            Only valid for `PRIVILEGED_MODE` type. On Checkpoint devices, this is used as the TACACS privilege level, as
            in TACP-15. If absent, the highest privilege level will be used. Has no effect for other kinds of devices.
          examples:
            - 15
        autoAssociate:
          type: boolean
          description: |-
            Whether this credential can be attempted on devices not explicitly configured to use it.
            Defaults to true.
    NewHttpCredential:
      type: object
      required:
        - type
        - name
        - password
      properties:
        type:
          $ref: '#/components/schemas/HttpCredentialType'
          examples:
            - LOGIN
        name:
          type: string
          description: For display purposes in the application
          examples:
            - admin (sjc)
        username:
          type: string
          description: Required for the `LOGIN` type
          examples:
            - admin
        password:
          type: string
          examples:
            - my-s3cr3t-p4s$w0rd
        loginType:
          $ref: '#/components/schemas/LoginType'
          description: Required only for a credential of type `LOGIN` used by a Silver Peak Orchestrator
          examples:
            - LOCAL
        autoAssociate:
          type: boolean
          description: Defaults to true for the `LOGIN` type. Not allowed for the `API_KEY` type.
          examples:
            - false
    StoredCliCredential:
      allOf:
        - $ref: '#/components/schemas/CliCredential'
        - $ref: '#/components/schemas/Attribution'
    StoredHttpCredential:
      allOf:
        - $ref: '#/components/schemas/HttpCredential'
        - $ref: '#/components/schemas/Attribution'
    CliCredentialType:
      type: string
      enum:
        - LOGIN
        - PRIVILEGED_MODE
        - EXPERT_MODE
        - SHELL
    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
    HttpCredentialType:
      type: string
      enum:
        - LOGIN
        - API_KEY
    LoginType:
      type: string
      enum:
        - LOCAL
        - RADIUS
        - TACACS
        - OAUTH
        - JWT
        - SAML
  securitySchemes:
    api_token:
      type: http
      scheme: basic
