{
  "openapi": "3.0.0",
  "info": {
    "title": "IronWiFi Console API",
    "description": "REST API for IronWiFi network management console. Manage WiFi networks, users, devices, certificates, and more. Supports multi-tenant operations for MSP partners.",
    "version": "1.0.0",
    "contact": {
      "name": "IronWiFi Support",
      "email": "support@ironwifi.com",
      "url": "https://www.ironwifi.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.ironwifi.com/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://console.ironwifi.io",
      "description": "Global (default)"
    },
    {
      "url": "https://europe-west1.ironwifi.io",
      "description": "Europe West"
    },
    {
      "url": "https://europe-west2.ironwifi.io",
      "description": "Europe West 2"
    },
    {
      "url": "https://us-central1.ironwifi.io",
      "description": "US Central"
    },
    {
      "url": "https://us-west1.ironwifi.io",
      "description": "US West"
    },
    {
      "url": "https://asia-southeast1.ironwifi.io",
      "description": "Asia Southeast"
    },
    {
      "url": "https://asia-east1.ironwifi.io",
      "description": "Asia East"
    },
    {
      "url": "https://australia-southeast1.ironwifi.io",
      "description": "Australia"
    },
    {
      "url": "https://africa-south1.ironwifi.io",
      "description": "Africa South"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    { "name": "Users", "description": "RADIUS user management" },
    { "name": "User Groups", "description": "User group organization and policies" },
    { "name": "Vouchers", "description": "Guest WiFi voucher generation" },
    { "name": "Devices", "description": "Device management and MAC authentication" },
    { "name": "Certificates", "description": "Certificate management for EAP-TLS" },
    { "name": "Profiles", "description": "Device onboarding profiles" },
    { "name": "RADIUS Servers", "description": "RADIUS server configuration" },
    { "name": "Networks", "description": "Network and SSID configuration" },
    { "name": "Captive Portals", "description": "Guest WiFi captive portal pages" },
    { "name": "Authentication Providers", "description": "External identity provider configuration" },
    { "name": "Policies", "description": "Access control policies and conditional access" },
    { "name": "Organizations", "description": "Multi-tenant organization management (MSP)" },
    { "name": "Operators", "description": "Admin operator accounts" },
    { "name": "Roles", "description": "Role-based access control" },
    { "name": "API Keys", "description": "API key management" },
    { "name": "Reports", "description": "Authentication logs and analytics" },
    { "name": "Bulk Operations", "description": "Batch create, update, and delete" },
    { "name": "RADIUS Dictionary", "description": "RADIUS attribute dictionary and vendors" },
    { "name": "Alert Contacts", "description": "Alert notification recipients" },
    { "name": "Webhooks", "description": "Webhook endpoint configuration" }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "description": "Retrieve a paginated list of RADIUS users",
        "operationId": "getUserCollection",
        "tags": ["Users"],
        "parameters": [
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/page_size" },
          { "$ref": "#/components/parameters/filter" },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort field and direction (e.g., username:asc)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of users",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserCollection"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "summary": "Create user",
        "description": "Create a new RADIUS user",
        "operationId": "createUser",
        "tags": ["Users"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UserInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/users/{user_id}": {
      "get": {
        "summary": "Get user",
        "description": "Retrieve a single user by ID",
        "operationId": "getUser",
        "tags": ["Users"],
        "parameters": [
          { "$ref": "#/components/parameters/user_id" }
        ],
        "responses": {
          "200": {
            "description": "User details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "patch": {
        "summary": "Update user",
        "description": "Update an existing user",
        "operationId": "updateUser",
        "tags": ["Users"],
        "parameters": [
          { "$ref": "#/components/parameters/user_id" }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UserInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete user",
        "description": "Delete a user by ID",
        "operationId": "deleteUser",
        "tags": ["Users"],
        "parameters": [
          { "$ref": "#/components/parameters/user_id" }
        ],
        "responses": {
          "204": { "description": "User deleted" }
        }
      }
    },
    "/user-groups": {
      "get": {
        "summary": "List user groups",
        "description": "Retrieve a paginated list of user groups",
        "operationId": "getUserGroupCollection",
        "tags": ["User Groups"],
        "parameters": [
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/page_size" }
        ],
        "responses": {
          "200": { "description": "Paginated list of user groups" }
        }
      },
      "post": {
        "summary": "Create user group",
        "description": "Create a new user group",
        "operationId": "createUserGroup",
        "tags": ["User Groups"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "description": "Group name" },
                  "comment": { "type": "string", "description": "Optional description" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "User group created" }
        }
      }
    },
    "/vouchers": {
      "get": {
        "summary": "List vouchers",
        "description": "Retrieve a paginated list of guest WiFi vouchers",
        "operationId": "getVoucherCollection",
        "tags": ["Vouchers"],
        "parameters": [
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/page_size" }
        ],
        "responses": {
          "200": { "description": "Paginated list of vouchers" }
        }
      },
      "post": {
        "summary": "Create vouchers",
        "description": "Generate one or more guest WiFi vouchers",
        "operationId": "createVoucher",
        "tags": ["Vouchers"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["table_id"],
                "properties": {
                  "table_id": { "type": "string", "description": "Target group ID" },
                  "duration": { "type": "integer", "description": "Voucher validity in seconds" },
                  "count": { "type": "integer", "description": "Number of vouchers to generate", "default": 1 }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Vouchers created" }
        }
      }
    },
    "/devices": {
      "get": {
        "summary": "List devices",
        "description": "Retrieve a paginated list of registered devices",
        "operationId": "getDeviceCollection",
        "tags": ["Devices"],
        "parameters": [
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/page_size" },
          { "$ref": "#/components/parameters/filter" }
        ],
        "responses": {
          "200": { "description": "Paginated list of devices" }
        }
      },
      "post": {
        "summary": "Register device",
        "description": "Register a new device for MAC authentication",
        "operationId": "createDevice",
        "tags": ["Devices"],
        "responses": {
          "201": { "description": "Device registered" }
        }
      }
    },
    "/certificates": {
      "get": {
        "summary": "List certificates",
        "description": "Retrieve certificates managed by the PKI",
        "operationId": "getCertificateCollection",
        "tags": ["Certificates"],
        "parameters": [
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/page_size" }
        ],
        "responses": {
          "200": { "description": "Paginated list of certificates" }
        }
      }
    },
    "/profiles": {
      "post": {
        "summary": "Generate onboarding profile",
        "description": "Generate a device enrollment profile for 802.1X configuration",
        "operationId": "createProfile",
        "tags": ["Profiles"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ssid": { "type": "string", "description": "Target SSID name" },
                  "eap_type": { "type": "string", "enum": ["EAP-TLS", "PEAP", "EAP-TTLS"], "description": "EAP method" },
                  "platform": { "type": "string", "enum": ["windows", "macos", "ios", "android", "chromeos"], "description": "Target platform" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Profile generated" }
        }
      }
    },
    "/keys": {
      "get": {
        "summary": "List API keys",
        "description": "Retrieve all API keys for the organization",
        "operationId": "getKeyCollection",
        "tags": ["API Keys"],
        "responses": {
          "200": { "description": "List of API keys" }
        }
      },
      "post": {
        "summary": "Create API key",
        "description": "Generate a new API key",
        "operationId": "createKey",
        "tags": ["API Keys"],
        "responses": {
          "201": { "description": "API key created" }
        }
      }
    },
    "/reports/{report_id}": {
      "get": {
        "summary": "Get report",
        "description": "Retrieve authentication logs and analytics reports",
        "operationId": "getReport",
        "tags": ["Reports"],
        "parameters": [
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report ID (e.g., 110 for authentication logs)",
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/page_size" }
        ],
        "responses": {
          "200": { "description": "Report data" }
        }
      }
    },
    "/organizations": {
      "get": {
        "summary": "List organizations",
        "description": "List all organizations (MSP multi-tenant)",
        "operationId": "getOrganizationCollection",
        "tags": ["Organizations"],
        "responses": {
          "200": { "description": "List of organizations" }
        }
      }
    },
    "/roles": {
      "get": {
        "summary": "List roles",
        "description": "List custom RBAC roles",
        "operationId": "getRoleCollection",
        "tags": ["Roles"],
        "responses": {
          "200": { "description": "List of roles" }
        }
      },
      "post": {
        "summary": "Create role",
        "description": "Create a custom role with specific permissions",
        "operationId": "createRole",
        "tags": ["Roles"],
        "responses": {
          "201": { "description": "Role created" }
        }
      }
    },
    "/dictionary": {
      "get": {
        "summary": "List RADIUS attributes",
        "description": "Retrieve the RADIUS attribute dictionary",
        "operationId": "getDictionary",
        "tags": ["RADIUS Dictionary"],
        "responses": {
          "200": { "description": "RADIUS attribute dictionary" }
        }
      }
    },
    "/vendors": {
      "get": {
        "summary": "List RADIUS vendors",
        "description": "Retrieve RADIUS vendors and vendor-specific attributes (VSAs)",
        "operationId": "getVendors",
        "tags": ["RADIUS Dictionary"],
        "responses": {
          "200": { "description": "RADIUS vendor list" }
        }
      }
    },
    "/bulk/{resource}": {
      "post": {
        "summary": "Bulk create",
        "description": "Create multiple resources in a single request",
        "operationId": "bulkCreate",
        "tags": ["Bulk Operations"],
        "parameters": [
          {
            "name": "resource",
            "in": "path",
            "required": true,
            "description": "Resource type (users, devices, vouchers)",
            "schema": { "type": "string", "enum": ["users", "devices", "vouchers"] }
          }
        ],
        "responses": {
          "200": { "description": "Bulk operation result" }
        }
      }
    },
    "/bulk/{resource}/async": {
      "post": {
        "summary": "Async bulk create",
        "description": "Start an asynchronous bulk operation",
        "operationId": "bulkCreateAsync",
        "tags": ["Bulk Operations"],
        "parameters": [
          {
            "name": "resource",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "202": { "description": "Bulk job started, returns job_id" }
        }
      }
    },
    "/bulk/status/{job_id}": {
      "get": {
        "summary": "Check bulk job status",
        "description": "Check the status of an asynchronous bulk operation",
        "operationId": "getBulkStatus",
        "tags": ["Bulk Operations"],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Job status" }
        }
      }
    },
    "/alertcontacts": {
      "get": {
        "summary": "List alert contacts",
        "description": "Retrieve configured alert notification recipients",
        "operationId": "getAlertContactCollection",
        "tags": ["Alert Contacts"],
        "responses": {
          "200": { "description": "List of alert contacts" }
        }
      },
      "post": {
        "summary": "Create alert contact",
        "description": "Add a new alert notification recipient",
        "operationId": "createAlertContact",
        "tags": ["Alert Contacts"],
        "responses": {
          "201": { "description": "Alert contact created" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token from Console > Account > API Keys"
      }
    },
    "parameters": {
      "page": {
        "name": "page",
        "in": "query",
        "description": "Page number for pagination",
        "required": false,
        "schema": { "type": "integer", "default": 1 }
      },
      "page_size": {
        "name": "page_size",
        "in": "query",
        "description": "Number of items per page",
        "required": false,
        "schema": { "type": "integer", "default": 25, "maximum": 100 }
      },
      "filter": {
        "name": "filter",
        "in": "query",
        "description": "Filter criteria as JSON or query parameter (e.g., filter[disabled]=0)",
        "required": false,
        "schema": { "type": "string" }
      },
      "user_id": {
        "name": "user_id",
        "in": "path",
        "required": true,
        "description": "User ID",
        "schema": { "type": "string" }
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique user ID" },
          "username": { "type": "string", "description": "Username (typically email)" },
          "disabled": { "type": "integer", "enum": [0, 1], "description": "0 = active, 1 = disabled" },
          "table_id": { "type": "string", "description": "Group ID the user belongs to" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "object",
                "properties": {
                  "href": { "type": "string" }
                }
              }
            }
          }
        }
      },
      "UserInput": {
        "type": "object",
        "required": ["username"],
        "properties": {
          "username": { "type": "string", "description": "Username (typically email)" },
          "password": { "type": "string", "description": "Password (for PEAP/EAP-TTLS)" },
          "table_id": { "type": "string", "description": "Group ID" },
          "disabled": { "type": "integer", "enum": [0, 1], "default": 0 }
        }
      },
      "UserCollection": {
        "type": "object",
        "properties": {
          "_embedded": {
            "type": "object",
            "properties": {
              "users": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/User" }
              }
            }
          },
          "page_count": { "type": "integer" },
          "page_size": { "type": "integer" },
          "total_items": { "type": "integer" },
          "page": { "type": "integer" },
          "_links": {
            "type": "object",
            "properties": {
              "self": { "type": "object", "properties": { "href": { "type": "string" } } },
              "first": { "type": "object", "properties": { "href": { "type": "string" } } },
              "last": { "type": "object", "properties": { "href": { "type": "string" } } },
              "next": { "type": "object", "properties": { "href": { "type": "string" } } },
              "prev": { "type": "object", "properties": { "href": { "type": "string" } } }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "type": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Invalid or missing API token",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "ValidationError": {
        "description": "Validation error - check required fields",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded (100 req/min)",
        "headers": {
          "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute" },
          "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining" },
          "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when limit resets" }
        },
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  }
}