مستندات فنی API Technical API Docs

لیست کامل کاربران. اگر کلید شما ادمین اصلی باشد، علاوه‌بر کاربران، ساختار نمایندگان (sub-admins) هم برگردانده می‌شود. اگر کلید شما متعلق به نماینده باشد، فقط کاربران همان نماینده برگردانده می‌شوند. List users. With a main admin key, it returns main-admin users plus sub-admins structure. With a sub-admin key, it returns only that sub-admin’s users.

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/users/list_all" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "main_admin": {
    "users": [
      {
        "username": "user1"
      }
    ]
  },
  "sub_admins": [
    {
      "id": 1,
      "username": "sa1",
      "users": [
        {
          "username": "sa_user1"
        }
      ]
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/users/list_all" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": true,
  "users": [
    {
      "username": "sa_user1"
    },
    {
      "username": "sa_user2"
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/users/list_all" 

{
  "success": false,
  "message": "API key is missing"
}

لیست تمام نودها به‌همراه وضعیت و ترافیک تجمیعی (از حافظه/STATE). List all nodes including status and aggregated traffic (from memory/STATE).

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/nodes" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "nodes": [
    {
      "id": 1,
      "name": "Node A",
      "ip_address": "1.2.3.4",
      "status": "active",
      "total_traffic_bytes": 123456
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/nodes" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": true,
  "nodes": [
    {
      "id": 1,
      "name": "Node A",
      "status": "active"
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/nodes" \
  -H "X-API-KEY: INVALID_KEY" 

{
  "success": false,
  "message": "Invalid or inactive API key"
}

ایجاد نود جدید و شروع نصب/Provision در پس‌زمینه (پاسخ 202). این متد فقط برای main_admin مجاز است. Create a new node and start provisioning in background (returns 202). Main-admin only.

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/nodes" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Node A",
  "ip_address": "1.2.3.4",
  "ssh_password": "pass",
  "openvpn_port": 1194,
  "protocol": "udp",
  "sync_all_users": false,
  "communication_method": "wireguard"
}'

{
  "success": true,
  "message": "Node created and installation started in background.",
  "node_id": 1
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/nodes" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Node B",
  "ip_address": "2.3.4.5",
  "ssh_password": "pass"
}'

{
  "success": false,
  "message": "Permission denied: Main admin API key required."
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/nodes" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Node C"
}'

{
  "success": false,
  "message": "Missing required fields: name, ip_address, ssh_password"
}

ویرایش نود و تریگر همگام‌سازی فقط برای سرویس‌هایی که تغییر کرده‌اند. (در کد فعلی محدودیت نقش برای PUT/DELETE نود اعمال نشده — فقط API key لازم است.) Edit node and trigger sync only for changed services. (Current code does not restrict role for node PUT/DELETE — only API key is required.)

curl -s -X PUT "http://YOUR_PANEL_DOMAIN/api/v1/nodes/1" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "openvpn_port": 443,
  "protocol": "tcp"
}'

{
  "success": true,
  "message": "Node updated. Sync triggered only for changed services."
}

curl -s -X PUT "http://YOUR_PANEL_DOMAIN/api/v1/nodes/1" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Node A (EU)",
  "ip_address": "5.6.7.8"
}'

{
  "success": true,
  "message": "Node updated. Sync triggered only for changed services."
}

curl -s -X PUT "http://YOUR_PANEL_DOMAIN/api/v1/nodes/999999" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "protocol": "udp"
}'

{
  "success": false,
  "message": "Node not found"
}

لیست پورت‌های پیش‌فرض و پورت‌های سفارشی اختصاص‌داده‌شده به سرورها. فقط main_admin. List default ports and custom port assignments per server. Main-admin only.

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/ports" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "default_ports": [
    {
      "is_default": true,
      "name": "Main Server",
      "public_port": 1194,
      "protocol": "udp"
    }
  ],
  "custom_ports": [
    {
      "port_id": 2,
      "server_identifier": "node_1",
      "public_port": 443,
      "protocol": "tcp",
      "server_name": "Node: Node A"
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/ports" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": false,
  "message": "Permission denied: Main admin API key required."
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/ports" \
  -H "X-API-KEY: INVALID_KEY" 

{
  "success": false,
  "message": "Invalid or inactive API key"
}

لیست سرورها (Main + Nodeها) برای مدیریت پورت‌ها. خروجی شامل idهای لازم مثل main و node_<id> است. فقط main_admin. List servers (Main + Nodes) for port management. Returns IDs like main and node_<id>. Main-admin only.

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/servers_for_ports" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "servers": [
    {
      "id": "main",
      "name": "Main Server"
    },
    {
      "id": "node_1",
      "name": "Node: Node A"
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/servers_for_ports" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": false,
  "message": "Permission denied: Main admin API key required."
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/servers_for_ports" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": false,
  "message": "An internal error occurred."
}

ایجاد/ثبت پورت و اختصاص آن به سرورهای انتخاب‌شده (server_ids). اگر پورت/پروتکل قبلاً وجود داشته باشد، فقط Assignmentها اضافه می‌شوند. فقط main_admin. Create/register a port and assign it to selected servers (server_ids). If the port/protocol already exists, only assignments are added. Main-admin only.

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/public/ports" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "public_port": 443,
  "protocol": "tcp",
  "server_ids": [
    "main",
    "node_1"
  ]
}'

{
  "success": true,
  "message": "Port configured on selected servers."
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/public/ports" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "public_port": 443,
  "protocol": "tcp",
  "server_ids": []
}'

{
  "success": false,
  "message": "Missing info."
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/public/ports" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "public_port": 443,
  "protocol": "tcp",
  "server_ids": [
    "main"
  ]
}'

{
  "success": false,
  "message": "Permission denied"
}

لیست تمام نمایندگان (Sub-Admins). فقط main_admin. List all sub-admins. Main-admin only.

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/sub_admins" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "sub_admins": [
    {
      "id": 1,
      "username": "sa1",
      "subscription_port": 2096,
      "panel_port": 8888,
      "max_users_limit": 100,
      "total_usage_quota_gb": 500
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/sub_admins" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": false,
  "message": "Permission denied"
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/sub_admins" \
  -H "X-API-KEY: INVALID_KEY" 

{
  "success": false,
  "message": "Invalid or inactive API key"
}

ایجاد نماینده جدید با اعتبارسنجی پورت‌ها و تنظیم فایروال. فقط main_admin. Create a new sub-admin with port validation and firewall setup. Main-admin only.

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/sub_admins" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "sa1",
  "password": "pass",
  "subscription_port": 2096,
  "panel_port": 8888,
  "max_users_limit": 100,
  "total_usage_quota_gb": 500,
  "is_active": true,
  "notes": "Reseller A",
  "allowed_servers": [
    "main",
    "node_1"
  ]
}'

{
  "success": true,
  "message": "Sub-admin created successfully and ports configured.",
  "sub_admin": {
    "id": 1,
    "username": "sa1"
  }
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/sub_admins" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "sa1",
  "password": "pass"
}'

{
  "success": false,
  "message": "A sub-admin with this username already exists."
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/sub_admins" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "sa2"
}'

{
  "success": false,
  "message": "Username and password are required."
}

دریافت تنظیمات عمومی سرور (فعلاً PSK). فقط main_admin. Get server settings (currently PSK). Main-admin only.

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/server_settings" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "settings": {
    "ipsec_psk": "EylanPanelKey123"
  }
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/server_settings" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": false,
  "message": "Permission denied: Main admin API key required."
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/server_settings" \
  -H "X-API-KEY: INVALID_KEY" 

{
  "success": false,
  "message": "Invalid or inactive API key"
}

به‌روزرسانی PSK برای IPsec روی سرور اصلی و تلاش برای اعمال روی نودها. فقط main_admin. مقدار PSK نباید خالی باشد و نباید شامل کوتیشن دابل (") باشد. Update IPsec PSK on main server and attempt to apply on nodes. Main-admin only. PSK must be non-empty and must not contain double quotes (").

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/update_ipsec_psk" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "new_psk": "MyNewSecurePSK_2026"
}'

{
  "success": true,
  "message": "IPsec PSK updated locally and on 2 nodes."
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/update_ipsec_psk" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "new_psk": ""
}'

{
  "success": false,
  "message": "Invalid PSK. Cannot be empty or contain double quotes."
}

curl -s -X POST "http://YOUR_PANEL_DOMAIN/api/v1/update_ipsec_psk" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "new_psk": "X"
}'

{
  "success": false,
  "message": "Permission denied: Main admin API key required."
}

لیست کامل سرورهای قابل انتخاب برای نمایندگان (برای پر کردن فیلد allowed_servers). فقط main_admin. Return all selectable servers for sub-admin creation (used for allowed_servers). Main-admin only.

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/all_selectable_servers" \
  -H "X-API-KEY: YOUR_MAIN_ADMIN_API_KEY" 

{
  "success": true,
  "servers": [
    {
      "id": "main",
      "name": "Main Server"
    },
    {
      "id": "node_1",
      "name": "Node: Node A"
    }
  ]
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/all_selectable_servers" \
  -H "X-API-KEY: YOUR_SUB_ADMIN_API_KEY" 

{
  "success": false,
  "message": "Permission denied: Main admin API key required."
}

curl -s "http://YOUR_PANEL_DOMAIN/api/v1/public/all_selectable_servers" \
  -H "X-API-KEY: INVALID_KEY" 

{
  "success": false,
  "message": "Invalid or inactive API key"
}