{
  "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": "/"
    }
  ],
  "security": [
    {
      "api_token": []
    }
  ],
  "tags": [
    {
      "name": "User Accounts",
      "description": "Manage user accounts"
    }
  ],
  "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"
                }
              }
            }
          }
        }
      },
      "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"
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{userId}": {
      "get": {
        "tags": [
          "User Accounts"
        ],
        "summary": "Gets a user account",
        "operationId": "getUserUsingGET",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "User Accounts"
        ],
        "summary": "Deletes a user account",
        "description": "**Warning**: This operation *cannot* be undone.",
        "operationId": "deleteUserUsingDELETE",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      },
      "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",
            "required": true,
            "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NewUser": {
        "type": "object",
        "required": [
          "email",
          "password"
        ],
        "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": {
        "type": "object",
        "required": [
          "id",
          "username",
          "enabled",
          "authSource"
        ],
        "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",
            "items": {
              "type": "string"
            },
            "description": "The names of any LDAP or SSO (SAML) groups to which this account belongs. Updated each time this user authenticates.",
            "examples": [
              "- netops"
            ]
          },
          "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"
      }
    }
  }
}