{
  "openapi": "3.1.0",
  "info": {
    "title": "Forward Networks: Credentials API",
    "summary": "Provide network device credentials needed for network collection",
    "description": "Device _credentials_ are the usernames, passwords, API keys, etc. that allow the Collector to authenticate to\nnetwork devices to retrieve the information needed to model them. Define any required device credentials first,\nthen reference them by ID in [classic devices](https://docs.fwd.app/latest/api/classic-devices/).\n\nNote: In the Forward Platform, only a Collector can read and use device passwords. For this reason, credential\n_write_ operations require the network’s Collector to be online.",
    "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": "Get all CLI credentials",
        "description": "Substitutes a system-generated identifier for each sensitive `password`.",
        "operationId": "getCliCredentials",
        "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": "Create a CLI credential",
        "operationId": "createCliCredential",
        "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": "Create CLI credentials",
        "description": "The response contains the same credentials as the request, in the same order.",
        "operationId": "createCliCredentials",
        "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": "Get a CLI credential",
        "description": "Substitutes a system-generated identifier for the sensitive `password`.",
        "operationId": "getCliCredential",
        "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"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Credentials"
        ],
        "summary": "Update a CLI credential",
        "description": "All JSON properties in the request body are optional. Include only the properties you wish to\nchange.",
        "operationId": "patchCliCredential",
        "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"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Credentials"
        ],
        "summary": "Delete a CLI credential",
        "operationId": "deleteCliCredential",
        "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": {}
          }
        }
      }
    },
    "/networks/{networkId}/http-credentials": {
      "get": {
        "tags": [
          "Credentials"
        ],
        "summary": "Get all HTTP credentials",
        "description": "Substitutes a system-generated identifier for each sensitive `password`.",
        "operationId": "getHttpCredentials",
        "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": "Create an HTTP credential",
        "operationId": "createHttpCredential",
        "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": "Create HTTP credentials",
        "description": "The response contains the same credentials as the request, in the same order.",
        "operationId": "createHttpCredentials",
        "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": "Get an HTTP credential",
        "description": "Substitutes a system-generated identifier for the sensitive `password`.",
        "operationId": "getHttpCredential",
        "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"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Credentials"
        ],
        "summary": "Update an HTTP credential",
        "description": "All JSON properties in the request body are optional. Include only the properties you wish to\nchange.",
        "operationId": "patchHttpCredential",
        "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": {}
          }
        }
      },
      "delete": {
        "tags": [
          "Credentials"
        ],
        "summary": "Delete an HTTP credential",
        "operationId": "deleteHttpCredential",
        "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": {}
          }
        }
      }
    }
  },
  "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\nmode password during a connectivity test or collection. If a privileged mode password is specified both here\nand 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\nin 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.\nDefaults 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\nmode password during a connectivity test or collection. If a privileged mode password is specified both here\nand 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\nin 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\nmode password during a connectivity test or collection. If a privileged mode password is specified both here\nand 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\nin 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.\nDefaults 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\nexist 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\ndeleted.",
            "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\nmight 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\nbeen 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"
      }
    }
  }
}