{
  "openapi" : "3.1.0",
  "info" : {
    "title" : "Forward Networks: User Accounts API",
    "description" : "Manage user accounts",
    "contact" : {
      "email" : "support@forwardnetworks.com"
    },
    "license" : {
      "name" : "MIT",
      "url" : "https://spdx.org/licenses/MIT"
    },
    "version" : "${apiVersion}"
  },
  "servers" : [
    {
      "url" : "/"
    }
  ],
  "tags" : [
    {
      "name" : "User Accounts",
      "description" : "User Controller"
    }
  ],
  "paths" : {
    "/api/users" : {
      "get" : {
        "tags" : [
          "User Accounts"
        ],
        "summary" : "Gets all user accounts",
        "operationId" : "getUsersUsingGET",
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Users"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      },
      "post" : {
        "tags" : [
          "User Accounts"
        ],
        "summary" : "Creates a user account",
        "description" : "Creates a new `LOCAL` user account.",
        "operationId" : "createUserUsingPOST",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/NewUser"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/User"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/api/users/{userId}" : {
      "get" : {
        "tags" : [
          "User Accounts"
        ],
        "summary" : "Gets a user account",
        "operationId" : "getUserUsingGET",
        "parameters" : [
          {
            "name" : "userId",
            "in" : "path",
            "description" : "userId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/User"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      },
      "delete" : {
        "tags" : [
          "User Accounts"
        ],
        "summary" : "Deletes a user account",
        "description" : "**Warning**: This operation *cannot* be undone.",
        "operationId" : "deleteUserUsingDELETE",
        "parameters" : [
          {
            "name" : "userId",
            "in" : "path",
            "description" : "userId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      },
      "patch" : {
        "tags" : [
          "User Accounts"
        ],
        "summary" : "Updates a user account",
        "description" : "All JSON properties in the request body are optional. Include only the properties you wish to change.",
        "operationId" : "updateUserUsingPATCH",
        "parameters" : [
          {
            "name" : "userId",
            "in" : "path",
            "description" : "userId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/UserPatch"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/User"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "NewUser" : {
        "required" : [
          "email",
          "password"
        ],
        "type" : "object",
        "properties" : {
          "email" : {
            "type" : "string",
            "examples" : [
              "me@example.com"
            ]
          },
          "username" : {
            "type" : "string",
            "description" : "Defaults to the value of `email`",
            "examples" : [
              "me@example.com"
            ]
          },
          "password" : {
            "type" : "string",
            "examples" : [
              "zF4H+K;5]qE~%9G=nbAk"
            ]
          },
          "isSupport" : {
            "type" : "boolean",
            "description" : "Defaults to `false`",
            "examples" : [
              false
            ]
          },
          "enabled" : {
            "type" : "boolean",
            "description" : "Defaults to `true`",
            "examples" : [
              true
            ]
          }
        }
      },
      "User" : {
        "required" : [
          "authSource",
          "enabled",
          "id",
          "username"
        ],
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "A system-generated identifier that can be used in API requests to manage this account",
            "examples" : [
              "55555"
            ]
          },
          "username" : {
            "type" : "string",
            "description" : "The identifier used to authenticate (log in) with this account",
            "examples" : [
              "me@example.com"
            ]
          },
          "email" : {
            "type" : "string",
            "description" : "The email address at which this user wishes to receive system-generated emails",
            "examples" : [
              "me@example.com"
            ]
          },
          "enabled" : {
            "type" : "boolean",
            "description" : "Whether authentication (login and API use) is currently permitted for this user account"
          },
          "authSource" : {
            "type" : "string",
            "description" : "How this user authenticates. `LOCAL` accounts exist only in the Forward Platform.",
            "examples" : [
              "SAML"
            ],
            "enum" : [
              "LOCAL",
              "TACACS",
              "SAML",
              "LDAP"
            ]
          },
          "externalGroups" : {
            "type" : "array",
            "description" : "The names of any LDAP or SSO (SAML) groups to which this account belongs. Updated each time this user authenticates.",
            "examples" : [
              [
                "netops"
              ]
            ],
            "items" : {
              "type" : "string"
            }
          },
          "isSupport" : {
            "type" : "boolean",
            "description" : "Whether this account belongs to Forward Networks support staff. `true` excludes the account from statistics shown on the Engagement dashboard."
          },
          "lastActive" : {
            "type" : "string",
            "description" : "The approximate time of the most recent authenticated request from this account",
            "examples" : [
              "2024-12-31T23:59:59.789Z"
            ]
          }
        }
      },
      "UserPatch" : {
        "type" : "object",
        "properties" : {
          "email" : {
            "type" : "string",
            "examples" : [
              "me@example.com"
            ]
          },
          "username" : {
            "type" : "string",
            "description" : "Changes the username of a user whose `authSource` is \"LOCAL\"",
            "examples" : [
              "me@example.com"
            ]
          },
          "password" : {
            "type" : "string",
            "description" : "Assigns a new temporary password to a user whose `authSource` is \"LOCAL\". The user will be prompted to choose a new password when they log in with this password.",
            "examples" : [
              "zF4H+K;5]qE~%9G=nbAk"
            ]
          },
          "isSupport" : {
            "type" : "boolean",
            "examples" : [
              false
            ]
          },
          "enabled" : {
            "type" : "boolean",
            "examples" : [
              true
            ]
          }
        }
      },
      "Users" : {
        "type" : "object",
        "properties" : {
          "users" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/User"
            }
          }
        }
      }
    },
    "securitySchemes" : {
      "api_token" : {
        "type" : "http",
        "scheme" : "basic"
      }
    }
  }
}