> ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an existing Appliance > Update an existing Appliance. ## OpenAPI ````json PUT /appliances/{id} { "openapi": "3.0.0", "info": { "title": "AppGate SDP Controller REST API", "version": "API version 24.0", "license": { "name": "Proprietary", "url": "https://www.appgate.com" }, "description": "# About\n This specification documents the REST API calls for the AppGate SDP Controller.\n\n Please refer to the REST API chapter in the manual or contact AppGate support with any questions about\n this functionality.\n# Getting Started\n Requirements for API scripting:\n - Access to the Admin/API TLS Connection (default port 8443) of a Controller appliance.\n (https://support.appgate.com/docs/adminapi-tls-connection-v6-6)\n - An API user with relevant permissions.\n (https://support.appgate.com/docs/configure-admin-roles-v6-6)\n - In order to use the simple login API, Admin MFA must be disabled or the API user must be excluded.\n (https://support.appgate.com/docs/mfa-for-admins-v6-6)\n# Base path\n HTTPS requests must be sent to the Admin Interface hostname and port, with **/admin** path.\n\n For example: **https://appgate.company.com:8443/admin**\n\n All requests must have the **Accept** header as:\n\n **application/vnd.appgate.peer-v24+json**\n\n An exception is made for the **/admin/version** endpoint which instead expects an **application/json** Accept header.\n# API Conventions\n API conventions are important to understand and follow strictly.\n\n - While updating objects (via PUT), entire object must be sent with all fields.\n - For example, in order to add a remedy method to the condition below:\n ```\n {\n \"id\": \"12699e27-b584-464a-81ee-5b4784b6d425\",\n \"name\": \"Test\",\n \"notes\": \"Making a point\",\n \"tags\": [\"test\", \"tag\"],\n \"expression\": \"return true;\",\n \"remedyMethods\": []\n }\n ```\n - send the entire object with updated and non-updated fields:\n ```\n {\n \"id\": \"12699e27-b584-464a-81ee-5b4784b6d425\",\n \"name\": \"Test\",\n \"notes\": \"Making a point\",\n \"tags\": [\"test\", \"tag\"],\n \"expression\": \"return true;\",\n \"remedyMethods\": [{\"type\": \"DisplayMessage\", \"message\": \"test message\"}]\n }\n ```\n\n - In case Controller returns an error (non-2xx HTTP status code), response body is JSON.\n The \"message\" field contains information about the error.\n HTTP 422 \"Unprocessable Entity\" has extra `errors` field to list all the issues with specific fields.\n\n - Empty string (\"\") is considered a different value than \"null\" or field being omitted from JSON.\n Omitting the field is recommended if no value is intended.\n Empty string (\"\") will be almost always rejected as invalid value.\n\n - There are common pattern between many objects:\n - **Configuration Objects**: There are many objects with common fields, namely \"id\", \"name\", \"notes\", \"created\"\n and \"updated\". These entities are listed, queried, created, updated and deleted in a similar fashion.\n - **Distinguished Name**: Users and Devices are identified with what is called Distinguished Names, as used in\n LDAP. The distinguished format that identifies a device and a user combination is\n \"CN=\\,CN=\\,OU=\\\". Some objects have the\n \"userDistinguishedName\" field, which does not include the CN for Device ID.\n This identifies a user on every device.", "x-logo": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAdcAAADMCAYAAAAh4uktAAAa1UlEQVR4nO3debgkVXmA8fcOAzOAwOAgIpHFQQbcARGXCEhEE0MkGkAF0RDF3UQTjRuKC0lcYtRozKIIAaNRk6CgUYkbAY0LsqmDIMKAuAEDjMAA4yydP75pvNPTt+ur6lPdfe+8v+ep55Gx69RXfavrVJ3lOyBJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJUrumxh3AHHQ8cGTFZ94BXDyCWLR52wp4ILAvsDewI7AI2BZYs2FbAfwMWA58b8P/1vCOAJ4KvB24bsyxSLPeFHAV0KnYPjKuADXnHQi8EfgqcBfV12LvdgPwSeBEYOcRxz6XPJ34PlcDHwL2HGs00ix3KLkb2O3AvcYUo+aeXYDXA5dTvzIdtK0FzgWOAeaP7Gzmhm7l2t1+DZwKLBlnUNJsdQb5G9fzxhSj5o49gH+g2Rtq3e064OVEU7Oq9Vau3W0NcDrRXC8pYQdgFfmb1dfHE6bmgG2JvrzVtF+p9m7LgaPaP8VZb6bKdXole/LYopNmkRdR/0a171gi1Wz2FOBaRl+p9m6fBe7X7qnOalWVawc4Z2zRSbPIt6l/g3rXWCLVbLQlcb2sZ/wVa3e7Efj9Nk96FrNylQp4KM1uTr8gbprSIIuBCxh/ZdpvWwf8ZXunPmtZuW7m5o07gDni+Q332wWf/DXYbsD5wOPHHcgM5hFv1B/EefPSPRxeP7ytiMQRTT0fOLtQLJpb9iAq1t2HKOMO4FvAD4k52LcSo4u3JBJK7AQ8DHgksNcQx3nphjK7Yw8kaShHM1yz2hocGKJN7QRcQbNragXwAeJtt84D9C7AnxIj2Zv27TqOINgsLA3p8wzfb/XakUetSbaQZgPklgMv2bD/sB4B/BfNKtkXFTj+bGflKg3h/kQWm2Er1yuxv0q/8UHqXT93EnMmS1SqvQ4ALqkZz91EGsbNmZXrZs4+1+GcAGxRoJylRBPeBQXKatNuwIOJeHclkhksIJJn3Elk8bmSSAC/cjwhpi0gRnkvJZLab0v0Qa4HfkX0TV5F9FVeueHfR+EYov8y63LgGcCydsLhYuAg4CQiZ3Hmel8AfIJ4+13VUly97k30He9DXKf3ArYhKvpVwE+Jv+My4JcFj7s98Kw+/75fYt89gBf2+febiVaDNmwFPIT4nvYmvqdFxKjv24Bb+M11/yNGd91L95gCrqb66fR84mZd9bnTRxt+yhbA7xI5Ua8h/+ayjrgpv4vcTWZUdgVeDXyZeBjIns/NwFnEw9R2Lca3GLipRlxnExXIqBxJDJDKxveeluN5JPBu4FLimsvG9UOideAQhm8xemCN42a3S4aMqdd9gVcQeaLr/P1WAP8JPBdzoWuEDiN3gT4T+OfE5+6g3Rt3HTsCbyKWHytxs7gM+GPGN6f3EOBzlGnCX0U8bCxtIc4P1YjjDMbT8vQo4u0mE+Nayj9cbUXk5f5BMoaq7Rrgz4mWiyYmuXJ9DPBpYtDksDHdAXwYcyJrBD5K9QV5M9FEdlDisx1ima9xWkA0/d1G+RtGhxhwc/TIziZu7OcXPofuto6o4HYpFOsB5N++zqJMd0RTB5NfLOALBY97LNH10Mbf80bgZdT/Xiexcn0Q8Zbaxve0FjgNlyNUSxaRa1Z8/7R9vpf4/DdHEn1/jyP6pNr4QfZu5wK/1eK5LAD+jjJP7FXbSvr3m9V1VvJ4F9HOwKW6jiE/kvjgIY+1O9GUP4pr87tEX3zWJFWu84FTGM2CDrfgyl5qwUvIXYD7Tdvnlcl9HjyC+KebAl7DaCqi6dtNRBL60vYibpCjPJcOscD49g1jfgi5t9ZfMVnNctlm7GGSpPwB0fc3yr/lKvIVx6RUrrsR85NHfd3/G/bHqqALqb7ovtuzz07EyMWq/d7dfvj3mE8MpBr1D7K7raXsnMhHEc174zqfS2jWTJzpk+8QCR4myXZEU39V3OuIkal1vZx6A5VKb++gesDTJFSuD6Xc+Igm24XYTKwCHkHugus3neJTif1uYDQDf7YEPpOIZxRbiSQahwC3T8C5XE3Mf85aSG6A0KWMt591Jg8imoirtrqpFU9i/H/LDvF2PqiCHXfleiD5AWZtbj/CTHMa0t9TfaHdRYy47fW7iX07wB+1egZxszgzGcsotvXAC4Y4n/2Ivs9xn0d3W0bMu8w4Jllm29fEJMl2u4xqe+eAWMdZuS5lvC01vdtlxHgUYVaguhYQzS+LKz73ceDZff59HtGMVpWI/b+Jvqa2nAy8teG+1wNfIvLeriCG6O9IzCF9KDF4pUkT0TrgScDXau63M3Ez2rXBMdcA/0sMErqOqKDnE+ezlBjlfQDN3hi/CjyZOK9BzgSeU/GZK4m++M1hQv+TiRHGTVbsWk0kYvk+0QJ0K7ADcB/iDftx5B96ep0IfKTPvy+m/5J7S4ksTYP8mP7JIn5BPMQPsgNx3TZZbGE1kV7zm0RCjRXENb4TkdjiccQDa5Pr/lxipa/N4VpVQc8g9wT3xAFlvDWx/1raG017GPXne94OvJ2oaKpMAYcSTeB189L+nJjwnjWPZlMOvk5M61iUOMZ9iAn41zc4TuYBJlPu5pJ7eleiUqzzHa8nujeOpnpgzTyi++BM6v8G7iQyQGW1nf7wP2rG3wG+ARxHbrT5jsCf0WzxiJOGOC9tpjI38msY/NS9J7lBGm9oIf5tgGsTx+5uvyZWV2k6WOFA6k+h+FSN8l9cs+xlRJahJrYmRlXfWuN4a4H9B5S5d6KM9cRI0M3B2dT7e55HJEpo4iFE5VbneBeRf5trs3I9tmbcVxNdUk1MEW/tdfp111DvQUSbud3JVYonJ8r6UqKcqyjfbP/2xHG7203EG+iwpoDXUW/UZ+ZGsDP1fvBnUmZ+6BKi2TF73G8y88NWpr/18gIxzwZPJf+drqPc2/wJ5Ebxd7fsiO22KtftiRaebLz/SpkUmfclulCyx70Aux2VdDK5H31mYevsk2eJyq1rV/JZdZYBDyh4bIib56rk8S+m+of5nmRZHeKNs6TtiHSK2ePPNBjpjYl9/6lw7JNoHvEQkfkubweOKHz8x5Jvjl5Bbl5nW5XrW5Jxdoh7VskKbgHw7zWO/7SCx9Yc1R2IVHUxfTFZ3kIiNWJVeWcUO4PIWJT5QfyS3ANCE0eT74cddAO9D/kE5H/TwnlANBNn11y9iP43uUwKzZe1FP8kOYrc97iO9gb6HUT+4fNVifLaqFy3I3ff6BC/9zbMJ+5zmRgubCkGzSFPJHcxPaNGmR9IlLeKGBU4rG3IrcxzF/EU36ZMC0CHwQ8qr0uW8WmajTrNuh+xlFkmlt/us3/mJvWkFuOfFNnmxle3HMdx5B7+rqX6umqjcn1poswOMdq6zTnROxDzWpte99I9Pk71RbSCaDbJ2i9RZocyGYyOSx7rrwocq8o8otm3Kpa1zDy9JtOEuJKYWtC2pyVi6QD/0mffbyT2GzQgai5YQq5CO39E8XwsEUuHGHU/SBuV67cSZa4iptO07fBELB0i+5jU147kmouq5qX1c1Gi3G8PFz6Qy8R0I81z49aV/WH2axJ9WHLf17d6Bhu7IBHPCjZ927kssd8k5RJuw2up/g7WA48eUTwPIDfAqaovvHTlumeivA7w5hplDiuz2ES/636zMI71IGeb7Lyw0xqU/RGq544eRCRn+EGD8iGahw5NfO5dxFJzo/BlIllE1dP/E4lFrXv/rcpNwPvqh9XYSUTT5iCLidSZl0z7t05rEeU9jJj0PyqfZeMR0Jm/5zmUecjMWE6kPKwaFZyJu6TfSXzm18A/th3INO+lOlHGYqL15aL2w9Fsk3m7bNpxv4jc0nXvbRx9VN6ZN4O2BjHN5IWJuFb02S/ztHxqy7H3miLX9/rKnv0yb7xtNwt/IhFDye0Ppx17PrkR5HXGMpTw6ERMHQYnein95npGorw6c8RL+WEirr8YQ1xjt1m+rtewP7msRE3eWiH6Bc9KfO54YKuGx3hI4jMXAz9pWH5T51CdIm0xm64yk1lrc5glzproJI/Z+7e4PbHPfeqHk7aY0U+XuHHa/15C9RzM1eRH4ZdyITGXtEqddV+HlTlWNk91yW3fQrHPOVaug2XWdLyLmPvVVL98pb12onlmoX0Snzm3YdnD+CXR51hlevxbUT3/dh3R7Dxqme+w92/xiwb7lHQ89QbhlXDDtP+dObdvMLruiq71NPt7tmWKyFU8W2Uq4DnHynVmC4n+1ipnEW+gTZ1HpEyskl28uVdmGagfNix7WJnsQ9PfXHeiepzAtcQDz6hlvsPet/ArE/u0+dTf9Jpqai2x8EVXZrGFcWWoWpb4TJPFIprYntm9IPmovqeJ4oCmmT2d3Aoa05uE9yRW9ahrOdFENsiTiXVCf1qz7MyP8qaaZZZyY/VHNhrBvF2hMttwQ/VHNon/isQ+T6gfSsqjgIe3VPZMriCaebsy1+YvW4qlxHFHNbo+c91PstkefyNWrjPLPNVfw8ZLpL2GWIuyDVsQeVDrzkXN5BW9u3Y0ZWTeMKeP1M6cy+rqj7Qi8x1u3fPfFyf2WUo0hS+vHdFgzy9cXkZvN0Dv99HPuK7NOxOf2bb1KELme5pkJXIbzzo2C/e3J7mh76cTnfoQP4Bj2wpogz+hfq7QzOdHdZPolXlzWTXtf2fOZVw/5Mx3eEfPf/+U3Ntrv7WBh7EN8KzCZWZ8o+e/MxXYuCqWzN9zVInpM9/TJJvt8Tdi5drfCVR/N+vYOPfvUeTWBx3GEtppJmxr7dgq9098pu5glkyZbWh6Ll9J7HcCZdPZHU2ZtJp1faHnv3sfNvoZV3/dJPUTZkaVT7Jbxx3AONgsvKl5xM2sypeIha67RtXM9nw2boouYdR9b3WOW3eK0P2IgU/95si2KXMu1/f5t89QnZx/L2Ku5zCj0qdbSeRnLmE+8CaqRx1fTgw2m67f99FrXOuCTtJ6pLcRucHH8UBUQukujVnBynVTh5PLzTl9INMDKbs83CB/RLwhryxY5hHk16ksZR9yqf0yI2qnmyLOp+SKQhmZ1Vr6nctXiQeIqiQeJwP/RWThGdY5NF+ou9fLyU3n6fdgkPnbPoYYWHhLnaCGtAXNFxdvy5VEtrZB7mY8I+WrfH/cAWgyZDLW3MTGN5S/TuxTcqszaCq77ugjapRZQianbO8TbybbVIdcYo6StiIedqrimql145TEvh3KLRBeyr3JLYG2hv5dD1uQW63pOW2eRB8HJ2LqAGcOKKN0hqZTE+WNOtmGlLaYXNLu903bZz4xd2+UlWuddIvZyvU9Ncoc1jwiV3JVTKf37JetXO9k0zmlbXpGMq6Zplvdj9ziEKuYrGw32YWzPz2gjM8m9h91kpMPJWIadeV6fKK8dVQnWZHG4k/J/aim98f8QXKf0tsjkueUrVzvYjRLVUH0aWdi6k3ika1cO1SvWlLKluTWtry6opz3J8roEMkqJmHe4CvIxbseOHBAOa9MlpMZvV/CPsSbdiamUVauuxKVZ1WZLvE2Iexz3VhmUNKFbNyHsCXwzsJxvIzqaSrPI25wpSwk5tC23QS3DfC2xOdWMVy/4InEMoCZqS7DeBGwd+JzVYOR3kVcf1VTifYl3gSPYHxzep8E/G3ys2cD3x3w/38KeDfVo6HfSSTUr8pHPay3U+a+uDbxmTqpJ39OrLxUtZLUC4iUqk0XE5GKeyS5p9UXjyCWjyTiyC7Onn1z7W7PLXgevabILTzfAT7aZ/86b64dImlBm2nj9iemk2Te3jJ5aDP90N3tbHJLIZb2++SasDtEF8uDEmV+MVneKQXPo58Tk3Fk3lwPS+z/vZrxnZCM6/tMRuuGBMS6oVUX7Z2MZjj84xOxdMgtxVW3cr0beGy5U9nI65MxrKf/akR1K9cO8ZbXxnzu+wLXJWP4XLLMLYkbY/bcziemHY3KccTbcja+NyfLfXKyvPXAM8ucyiYOpt65VVWueyf2XwvsXCPGhcQbbCa2/6bs3Oiu7Ym34xcmtlE15WuCbU1MdK66YPu9TbVhihh6XxVPZqBH3cq1Q4wALfnDmCLmVWb6jLo3hn6aVK4d4m25ZKafJeQGZHW3Og8r+5N/M+wQc0UPHvaEKmwDfLhGTB3iIaFOs+d3kuXeSfkK9jByo57rVK7zya3V/Iaasb6qRnxnUTZj2b2JReuzx2+SZ11zzLPJXSxV/R0lvS4Rzzqq50c2qVw7xHzKlxY4j62Bj9U87kxr0DatXDvEzbtEJqrDiCb57HE/2eAYmYXke6+Dfya30ERdR5BbEHv69ivqLzN2MPFmmil/PdFvXyL94EuIa67JNTWocoVY+rCqjJXUG+G7EPhxjRi/VbP8mexPDMrLHvc/CxxTc8BXqL5YfszocolCjA7MjFo8uaKcppVrdzuPGEhS1zxicNS1NY83aKDMMJVr96Z/Es2e5vcgbqbZt+8OkVmnaYWemdfYu91K9EsOu8D6FNFycX6DGNYTiU6aOKPmsb5D83Sg+wP/U/N4vVtV5fqKZDk/oF66xafUjHMV0SXTpPVmR2IwWZ0HkNuB3RocS3PMEnJPzCeNIbZMxbicwX2Kw1au3RvmOcRcux0rYt6LaLq6rMFxLmXwIJ1hK9fu9jNiZPSBDH5gWkgM4DmVek213e34AWVXmU+kRmxyfqs37Pss8n1684nv9xTimmr63f55w/OFyDx2TYNjfoHoD15UUf42xBSZT1LvIWmmrapy3ZncvPnuNflM8g/w/9Qg3hVERflwBt8z5hHZoN5HLjlK7/ai5DnMaaN8E5tUbyNyow6yjlgpp+5aqsM6ilzzypOIJqh+Pkc07ZWylhjmfznxY72TGJG7O/GjzYwO7ec24gc9KCXeAcBFDcufyc+J87maGPk7n7hJLyVS7zUdbXwqMfBjGAuJJAuHD1FGh/hOLyfO8Wbiu96GaEbeifibPZLh++feCrxlyDIOIt6Y6/TXdq0hVt75AfFbvYP4++1MJN84mLJ97x+lenT9vxDN/FnXEg8Ly4mWlq5T2Xga0kLg/4g38CZuJpqMbyDWrp1HDFbam/idLW5Y7oepd76ao7Yg8rpWPYl9fkzxbUUs/l0V38cHlFHizbXt7W5yA6hKvbm2vZ1L/O1KWEAuJec4t/XEWsalHE08xI37vKq2qjdXiG6B2wocq9/1tCvDtTKU3r4+Q5zaDP0euYvm6HEFCLx3QFzd7S5mbq6d9Mp1NfGGnjEbKtcLKD+3dh7RF50d8DPK7S7amR5zIpNfwWYqV4iBgcMea6ZKaykxYnzc38X5zN5Ve9SCT1F90dzEeJ/GHjZDXL3bTMuWTXLlejvRpJ016ZXrObS7uPcf0mzKSFvbMtpdrvBo8n2W49iylSsM3/ow6B60O9HsP67v4fOUnfKjWW4ncpPGR5nQfiYXUh3nxTPsm6lc30ezgQvDbJcz85SbmWQq10uISm6U57KOGAjUxqT9XruP4fx6t7XAB2j3QaLrIEbf9HkruSxpdSrXheRmJcy0VT3gLyLmtY76un8nkfxEuscryV1Ak7AKyUvIxdpvcEOmcj2EGDX91eRxhv1BfhDYtsH3kKlczyMG6r2M3HJmw25XM9yAo6aOpN68w1Lb+cB+7Z/eRnYkKrJRNIufSwxePDLx2TqVK0T/+WkN48q0nk0R94qVhb+Tftv1mIFJM/ge1RfQt8cW3cYWkcv28oE++2YrV4gf57NpNh0ie2MetEJKlWzl2rUrMXeyjb67XxHp/Ubx9jaTLYl8s5lsXsNuXyPGKIzTocQiAG2c3xXAMdOO1Ubl2vUX1E+1WKdrahdiucbs6j51tpXE3HpzF6uvR5G7kCZpvlYmy9HNbDpPtE7l2rUl8CfkmqOrtrUbYnjCkOcP9SvXrqXEvMASozavJyrVqvm+o7QFMR/3EzSbjzvTdgPxwDbMA1EbnkIkgCgxV/UC4Fg2bdLPLCXZtHKFyGB1Dvm38SbjPpYA/0iZN9lrialWbWQB0xySmYC9iska/XY4uR/BsT37Nalcp3s4UZl8k/zT9m0bjvtnlF20vGnl2nUvYrGDjxHzILM3lmVEJXM47SwCUNIORIakfyD6teu8td9FVDZvI9I8TvqSlPcn3gI/TwyOy5zjKuIaeS2DVyqaIgaQDUqGMkzl2vVwYsxD1ZTAYQZVLiSu+38lv9jEGiKpyweJ+4M5EWraXL+w11Ndcf6I6B+ZFPOICfpVP7JLiTeYrkwSiUOJJtsqC4k+6CVEerNtiVGCK4mb20+I5rXl5NazrCuTROJ/yb8l70a8QTyAeBPdgUjzdgcxSvxHRJPrLQ1inRQLiDf3fYi3jkXEQ8ZqoqK5g/i7XUXceNteL7Ut84m/475Epbs98fe8jXhouI7o7ug+cGRNEaOW38ymA/AySSTq2IuobB9ANLtO73I4iXhTL2EXfnPdLyauhzXEdX4LcT1cRnRFSZrBsG+uk2TYN1epqXlEn+wVlH1z1Rw16U1ckjQJ1gP/ATyYaGK9arzhaNJNep+KJE2SbiX7GerP09ZmxDdXSaqvO+BH6svKVZKkwqxcJUkqzMpVkqTCrFwlSSrMylWSpMKsXCVJKszKVZKkwqxcJUkqzMpVkqTCrFwlSSrMylWSpMKsXCVJKszKVZKkwqxc5767xx1AQauJJb8kaaJZuc59xwF/DFw+7kAKWAYsBd7P3HpokCTNUvOApwL/B3R6tkPGGFdT9wXeAtzKxudy3vhCkiRtzh4PfJZoYp2tlWvX9sArgJ9h5SpJmgD7Af8OPG7McZSwNfBS4LRxByJJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiRJkiS17f8B39C5qj6jPb0AAAAASUVORK5CYII=", "href": "#" }, "contact": { "name": "AppGate SDP Support", "url": "https://support.appgate.com/docs", "email": "appgatesdp.support@appgate.com" } }, "servers": [ { "url": "https://appgate.company.com:8443/admin" } ], "security": [ { "BearerAuth": [] } ], "x-tagGroups": [ { "name": "Authentication & Authorization", "tags": [ "Version", "Login" ] }, { "name": "Dashboard", "tags": [ "Top Entitlements", "User Logins Per Hour", "Devices On-Boarded Per Hour" ] }, { "name": "Admin Messages", "tags": [ "Admin Messages" ] }, { "name": "Access", "tags": [ "Policies", "Conditions", "Entitlements", "Risk Model", "Ringfence Rules", "Admin Roles", "Criteria Scripts", "Entitlement Scripts" ] }, { "name": "Identity", "tags": [ "Client Profiles", "Identity Providers", "IP Pools", "MFA Providers", "Device Claim Scripts", "User Claim Scripts", "Local Users", "Service Users" ] }, { "name": "System", "tags": [ "Appliances", "Replication Targets", "Sites", "Tags", "Appliance Customizations", "Trusted Certificates", "Secrets Manager", "Client Auto-Update", "Certificate Authority", "Appliance Change", "Appliance Upgrade", "Appliance Backup", "Appliance Metrics" ] }, { "name": "Usage", "tags": [ "Active Sessions", "Client Logs", "Discovered Apps", "Health", "Registered Devices", "Blacklisted Users", "Licensed Users", "Default Time-Based OTP Provider Seeds", "FIDO2 Devices", "Issued Certificates" ] }, { "name": "Settings", "tags": [ "Global Settings", "MFA for Admins", "License", "ZTP", "Replication Source" ] }, { "name": "Other", "tags": [ "Admin Preferences" ] } ], "paths": { "/appliances/{id}": { "put": { "summary": "Update an existing Appliance.", "description": "Update an existing Appliance.", "tags": [ "Appliances" ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Updated Appliance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Appliance" } } } }, "400": { "$ref": "#/components/responses/JsonError" }, "401": { "$ref": "#/components/responses/TokenError" }, "402": { "$ref": "#/components/responses/PaymentError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "406": { "$ref": "#/components/responses/responses-NotAcceptableError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/UnexpectedError" } }, "requestBody": { "$ref": "#/components/requestBodies/Appliance" } } } }, "components": { "parameters": { "id": { "name": "id", "in": "path", "description": "ID of the object.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "12699e27-b584-464a-81ee-5b4784b6d425" } } }, "schemas": { "Appliance": { "allOf": [ { "$ref": "#/components/schemas/BaseEntity" }, { "type": "object", "description": "Represents an Appliance.", "required": [ "hostname", "clientInterface", "networking" ], "properties": { "activated": { "type": "boolean", "readOnly": true, "description": "Whether the Appliance is activated or not. If it is not activated, it won't be accessible by the Clients." }, "pendingCertificateRenewal": { "type": "boolean", "readOnly": true, "description": "Whether the Appliance is pending certificate renewal or not. Should be true for a very short period on certificate renewal.", "example": false }, "version": { "type": "integer", "readOnly": true, "description": "Peer version of the Appliance.", "example": 9 }, "hostname": { "type": "string", "description": "Hostname of the Appliance. It's used by other Appliances to communicate with and identify this Appliances. Set it to \"automatic.hostname.assignment\" for cloud appliances in order for it to automatically configure the hostname on activation.", "example": "appgate.company.com" }, "site": { "type": "string", "format": "uuid", "x-uuid-ref": "Site", "description": "Site assigned to the Appliance.", "example": "4c07bc67-57ea-42dd-b702-c2d6c45419fc" }, "siteName": { "type": "string", "readOnly": true, "description": "Name of the Site for this Appliance. For convenience only.", "example": "Default Site" }, "customization": { "type": "string", "x-uuid-ref": "ApplianceCustomization", "format": "uuid", "description": "Customization assigned to this Appliance.", "example": "4c07bc67-57ea-42dd-b702-c2d6c45419fc" }, "clientInterface": { "type": "object", "description": "The details of the Client connection interface.", "required": [ "hostname" ], "properties": { "proxyProtocol": { "description": "To enable/disable Proxy protocol on this Appliance.", "type": "boolean", "default": false }, "hostname": { "type": "string", "description": "Hostname to connect by the Clients. It will be used to validate the Appliance Certificate. Set it to \"automatic.hostname.assignment\" for cloud appliances in order for it to automatically configure the hostname on activation.", "example": "appgate.company.com" }, "localHostname": { "type": "string", "description": "Load hostname that would take effect with Local Site Detection feature." }, "httpsPort": { "type": "integer", "description": "Port to connect for the Client specific services.", "default": 443 }, "dtlsPort": { "type": "integer", "description": "Port to connect for the Clients that connects to vpnd on DTLS if enabled.", "default": 443 }, "stunPort": { "type": "integer", "description": "Port to connect for STUN/TURN services.", "default": 443 }, "allowSources": { "$ref": "#/components/schemas/AllowSources" }, "overrideSpaMode": { "type": "string", "description": "Override SPA mode for this appliance.", "enum": [ "TCP", "UDP-TCP" ] } } }, "adminInterface": { "type": "object", "description": "The details of the admin connection interface. Required on Controllers and LogServers.", "required": [ "hostname", "httpsCiphers" ], "properties": { "hostname": { "type": "string", "description": "Hostname to connect to the admin interface. This hostname will be used to validate the appliance certificate. Set it to \"automatic.hostname.assignment\" for cloud appliances in order for it to automatically configure the hostname on activation.", "example": "appgate.company.com" }, "httpsPort": { "type": "integer", "description": "Port to connect for admin services.", "default": 8443 }, "httpsCiphers": { "type": "array", "description": "The type of TLS ciphers to allow. See: https://www.openssl.org/docs/man1.0.2/apps/ciphers.html for all supported ciphers.", "items": { "type": "string" }, "default": [ "TLS13-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384" ] }, "allowSources": { "$ref": "#/components/schemas/AllowSources" }, "httpsP12": { "$ref": "#/components/schemas/P12" } } }, "networking": { "type": "object", "description": "Networking configuration of the system.", "properties": { "hosts": { "type": "array", "description": "/etc/hosts configuration", "items": { "type": "object", "required": [ "hostname", "address" ], "properties": { "hostname": { "type": "string", "description": "Hostname to map IP to.", "example": "internal.service.company.com" }, "address": { "type": "string", "description": "IP for the given hostname for appliance to resolve.", "example": "10.10.10.10" } } } }, "nics": { "type": "array", "description": "System NIC configuration", "items": { "type": "object", "required": [ "name" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the NIC is active or not.", "example": true }, "name": { "type": "string", "description": "NIC name", "example": "eth0" }, "ipv4": { "type": "object", "description": "IPv4 settings for this NIC.", "properties": { "dhcp": { "type": "object", "description": "IPv4 DHCP configuration for the NIC.", "properties": { "enabled": { "type": "boolean", "description": "Whether DHCP for IPv4 is enabled." }, "dns": { "type": "boolean", "description": "Whether to use DHCP for setting IPv4 DNS settings on the appliance." }, "routers": { "type": "boolean", "description": "Whether to use DHCP for setting IPv4 default gateway on the appliance." }, "ntp": { "type": "boolean", "description": "Whether to use DHCP for setting NTP on the appliance." }, "mtu": { "type": "boolean", "description": "Whether to use DHCP for setting MTU on the appliance." } } }, "static": { "type": "array", "description": "IPv4 static NIC configuration for the NIC.", "required": [ "address", "netmask" ], "items": { "type": "object", "properties": { "address": { "type": "string", "description": "IPv4 Address of the network interface.", "example": "10.10.10.1" }, "netmask": { "type": "integer", "description": "Netmask of the network interface.", "example": 24 }, "snat": { "type": "boolean", "description": "Enable SNAT on this IP." } } } }, "virtualIp": { "type": "string", "description": "Virtual IP to use for IPv4.", "example": "10.10.10.24" } } }, "ipv6": { "type": "object", "description": "IPv6 settings for this NIC.", "properties": { "dhcp": { "type": "object", "description": "IPv6 DHCP configuration for the NIC.", "properties": { "enabled": { "type": "boolean", "description": "Whether DHCP for IPv6 is enabled." }, "dns": { "type": "boolean", "description": "Whether to use DHCP for setting IPv6 DNS settings on the Appliance." }, "ntp": { "type": "boolean", "description": "Whether to use DHCP for setting NTP on the appliance." }, "mtu": { "type": "boolean", "description": "Whether to use DHCP for setting MTU on the appliance." } } }, "static": { "type": "array", "description": "IPv6 static NIC configuration for the NIC.", "items": { "type": "object", "required": [ "address", "netmask" ], "properties": { "address": { "type": "string", "description": "IPv6 Address of the network interface.", "example": "2001:db8:0:0:0:ff00:42:8329" }, "netmask": { "type": "integer", "description": "Netmask of the network interface.", "example": 24 }, "snat": { "type": "boolean", "description": "Enable SNAT on this IP." } } } }, "virtualIp": { "type": "string", "description": "Virtual IP to use for IPv6.", "example": "2001:db8:0:0:0:ff00:42:8400" } } }, "mtu": { "type": "integer", "description": "MTU setting for the NIC. If left empty, appliance default will be used.", "example": 1500 } } } }, "dnsServers": { "type": "array", "description": "DNS Server addresses.", "items": { "type": "string" }, "example": [ "172.17.18.19", "192.100.111.31" ] }, "routes": { "type": "array", "description": "System route settings.", "items": { "type": "object", "required": [ "address", "netmask" ], "properties": { "address": { "type": "string", "description": "Address to route.", "example": "10.0.0.0" }, "netmask": { "type": "integer", "description": "Netmask for the subnet to route.", "example": 24 }, "gateway": { "type": "string", "description": "Gateway to use for routing.", "example": "10.0.0.254" }, "nic": { "type": "string", "description": "NIC name to use for routing.", "example": "eth0" } } } } } }, "ntp": { "type": "object", "description": "NTP configuration.", "properties": { "servers": { "type": "array", "items": { "type": "object", "description": "NTP server.", "required": [ "hostname" ], "properties": { "hostname": { "type": "string", "description": "Hostname or IP of the NTP server.", "example": "0.ubuntu.pool.ntp.org" }, "keyType": { "type": "string", "description": "Type of key to use for secure NTP communication.", "enum": [ "MD5", "SHA", "SHA1", "SHA256", "SHA512", "RMD160" ] }, "keyNo": { "type": "integer", "description": "Identifier number for the key." }, "key": { "format": "password", "type": "string", "description": "Key to use for secure NTP communication.", "writeOnly": true } } } } } }, "sshServer": { "type": "object", "description": "SSH server configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether the SSH Server is enabled on this appliance or not.", "default": false }, "port": { "type": "integer", "description": "SSH port.", "default": 22 }, "allowSources": { "$ref": "#/components/schemas/AllowSources" }, "passwordAuthentication": { "type": "boolean", "description": "Whether SSH allows password authentication or not.", "default": true } } }, "snmpServer": { "type": "object", "description": "SNMP Server configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether the SNMP Server os enabled on this appliance or not.", "default": false }, "tcpPort": { "type": "integer", "description": "TCP port for SNMP Server.", "example": 161 }, "udpPort": { "type": "integer", "description": "UDP port for SNMP Server.", "example": 161 }, "snmpd.conf": { "description": "Raw SNMP configuration.", "type": "string" }, "allowSources": { "$ref": "#/components/schemas/AllowSources" } } }, "healthcheckServer": { "type": "object", "description": "Healthcheck Server configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Healthcheck Server is enabled on this appliance or not.", "default": false }, "port": { "type": "integer", "description": "Port to connect for Healthcheck Server.", "default": 5555 }, "allowSources": { "$ref": "#/components/schemas/AllowSources" } } }, "prometheusExporter": { "$ref": "#/components/schemas/PrometheusExporter" }, "ping": { "type": "object", "description": "Rules for allowing ping.", "properties": { "allowSources": { "$ref": "#/components/schemas/AllowSources" } } }, "collectiveReplication": { "type": "object", "description": "Collective Replication settings.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Collective Replication Service is enabled on this Appliance or not. It's managed by registering and unregistering Replication Source.", "readOnly": true }, "paused": { "type": "boolean", "description": "Whether the Collective Replication Service is paused due to licensing state.", "readOnly": true } } }, "logServer": { "type": "object", "description": "Log Server settings. Log Server collects audit logs from all the appliances and stores them.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Log Server is enabled on this appliance or not.", "default": false }, "retentionDays": { "type": "integer", "description": "How many days of audit logs will be kept.", "default": 30 } } }, "controller": { "type": "object", "description": "Controller settings.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Controller is enabled on this appliance or not. Cannot be enabled on an inactive Appliance since some checks need to be done first.", "default": false } } }, "gateway": { "type": "object", "description": "Gateway settings.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Gateway is enabled on this appliance or not.", "default": false }, "suspended": { "type": "boolean", "description": "Whether the Gateway is in suspended mode or not. Suspended state will keep the existing Client connections but will reject new ones.", "default": false }, "vpn": { "type": "object", "description": "VPN configuration.", "properties": { "weight": { "type": "integer", "description": "Load balancing weight.", "default": 100 }, "localWeight": { "type": "integer", "description": "Load balancing weight that would take effect with Local Site Detection feature." }, "allowDestinations": { "type": "array", "description": "Destinations to allow tunnels to.", "items": { "type": "object", "required": [ "nic" ], "properties": { "address": { "type": "string", "description": "IP address to allow connection.", "example": "192.168.111.0" }, "netmask": { "type": "integer", "description": "Netmask to use with address for allowing connections.", "example": 24 }, "nic": { "type": "string", "description": "NIC name to accept connections on.", "example": "eth1" } } } } } } } }, "logForwarder": { "type": "object", "description": "LogForwarder settings. LogForwarder collects audit logs from the appliances in the given sites and sends them to the given endpoints.", "properties": { "enabled": { "type": "boolean", "description": "Whether the LogForwarder is enabled on this appliance or not.", "default": false }, "elasticsearch": { "allOf": [ { "$ref": "#/components/schemas/Elasticsearch" } ] }, "tcpClients": { "type": "array", "description": "TCP endpoints to connect and send the audit logs with the given format.", "items": { "$ref": "#/components/schemas/TcpClient" } }, "awsKineses": { "type": "array", "description": "AWS Kinesis endpoints to connect and send the audit logs with the given format.", "items": { "$ref": "#/components/schemas/AwsKinesis" } }, "sumoLogicClients": { "type": "array", "description": "SumoLogic endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/SumoLogic" } }, "splunkClients": { "type": "array", "description": "Splunk endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/Splunk" } }, "azureMonitors": { "type": "array", "description": "Azure Monitor endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/AzureMonitor" } }, "falconLogScales": { "type": "array", "description": "Falcon LogScale endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/FalconLogScale" } }, "datadogs": { "type": "array", "description": "Datadog endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/Datadog" } }, "coralogixs": { "type": "array", "description": "Coralogix endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/Coralogix" } }, "kafkaClients": { "type": "array", "description": "Kafka endpoints to connect and send the audit logs to.", "items": { "$ref": "#/components/schemas/Kafka" } }, "sites": { "type": "array", "description": "The sites to collect logs from and forward.", "items": { "type": "string", "format": "uuid", "x-uuid-ref": "Site", "description": "UUID of a site. Use '6f6fa9d9-17b2-4157-9f68-e97662acccdf' to collect logs from all the appliances. Use '6263435b-c9f6-4b7f-99f8-37e2e6b006a9' to collect logs from appliances without a site.\n" } } } }, "metricsAggregator": { "type": "object", "description": "Metrics Aggregator settings. It collects metrics from the appliances in the given sites and provides Prometheus APIs for consumption.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Metrics Aggregator is enabled on this appliance or not.", "default": false }, "prometheusExporter": { "$ref": "#/components/schemas/PrometheusExporter" }, "sites": { "type": "array", "description": "The sites to collect metrics from.", "items": { "type": "string", "format": "uuid", "x-uuid-ref": "Site", "description": "UUID of a site. Use '6f6fa9d9-17b2-4157-9f68-e97662acccdf' to collect logs from all the appliances. Use '6263435b-c9f6-4b7f-99f8-37e2e6b006a9' to collect logs from appliances without a site.\n" } } } }, "connectionBroker": { "type": "object", "description": "Connection Broker settings.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Connection Broker is enabled on this appliance or not.", "default": false }, "sites": { "type": "array", "description": "The sites to broker connections for.", "items": { "type": "string", "format": "uuid", "x-uuid-ref": "Site", "description": "UUID of a site. Use '6f6fa9d9-17b2-4157-9f68-e97662acccdf' to broker connections for all the appliances. Use '6263435b-c9f6-4b7f-99f8-37e2e6b006a9' to broker connections for appliances without a site.\n" } } } }, "connector": { "type": "object", "description": "Connector settings.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Connector is enabled on this appliance or not.", "default": false }, "expressClients": { "type": "array", "description": "A list of Clients to run on the appliance with the given configuration. The Clients will get the necessary tokens automatically according to the Site assigned to this Appliance. Currently only one allowed.", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name for the Client. It will be mapped to the user claim 'clientName'.", "example": "Printers" }, "deviceId": { "type": "string", "format": "uuid", "description": "The device ID to assign to this Client. It will be used to generate device distinguished name.", "example": "12699e27-b584-464a-81ee-5b4784b6d425" }, "allowResources": { "$ref": "#/components/schemas/AllowResources" }, "snatToResources": { "type": "boolean", "description": "Use SNAT for outgoing traffic from the Express Connector, endpoints will see traffic as coming from the Connector itself", "default": true }, "dnatToResource": { "type": "boolean", "description": "Apply destination NAT to traffic from tunnel into a resource", "default": false } } } }, "advancedClients": { "type": "array", "description": "A list of Clients to run on the appliance with the given configuration. Requires manual Policy configuration.", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name for the Client. It will be mapped to the user claim 'clientName'.", "example": "Printers" }, "deviceId": { "type": "string", "format": "uuid", "description": "The device ID to assign to this Client. It will be used to generate device distinguished name.", "example": "12699e27-b584-464a-81ee-5b4784b6d425" }, "allowResources": { "$ref": "#/components/schemas/AllowSources" }, "snatToTunnel": { "type": "boolean", "description": "Use Source NAT for the Client tunnel.", "default": true }, "snatToResources": { "type": "boolean", "description": "Use Source NAT for the resources.", "default": true }, "dnatToResource": { "type": "boolean", "description": "Apply destination NAT to traffic from tunnel into a resource", "default": false }, "defaultGateway": { "type": "boolean", "description": "Use this connector client as a default gw for local resources", "default": false }, "dhcpRelay": { "type": "object", "description": "Enable DHCP relay for this Connector.", "properties": { "servers": { "type": "array", "description": "DHCP servers to relay.", "items": { "type": "string", "description": "IPv4 address." } } } } } } } } }, "portal": { "$ref": "#/components/schemas/Portal" }, "rsyslogDestinations": { "type": "array", "description": "Rsyslog destination settings to forward appliance logs.", "items": { "type": "object", "required": [ "destination" ], "properties": { "selector": { "type": "string", "description": "Rsyslog selector.", "example": ":msg, contains, \"[AUDIT]\"", "default": "*.*" }, "template": { "type": "string", "description": "Rsyslog template to forward logs with.", "example": "%msg:9:$%\n", "default": "%HOSTNAME% %msg%" }, "destination": { "type": "string", "description": "Rsyslog server destination.", "example": "@@10.10.10.2" } } } }, "hostnameAliases": { "type": "array", "description": "Hostname aliases. They are added to the Appliance certificate as Subject Alternative Names so it is trusted using different IPs or hostnames. Requires manual certificate renewal to apply changes to the certificate.", "items": { "type": "string" }, "example": [ "appgatealias.company.com", "alias2.appgate.company.com" ] } } } ] }, "BaseEntity": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the object.", "example": "4c07bc67-57ea-42dd-b702-c2d6c45419fc" }, "name": { "type": "string", "description": "Name of the object.", "example": "object" }, "notes": { "type": "string", "description": "Notes for the object. Used for documentation purposes.", "example": "This object has been created for test purposes." }, "created": { "type": "string", "format": "date-time", "description": "Create date.", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "description": "Last update date.", "readOnly": true }, "readOnly": { "type": "boolean", "description": "Whether the entity is protected from manual updates and deletes.", "example": false, "readOnly": true }, "tags": { "type": "array", "description": "Array of tags.", "items": { "type": "string" }, "example": [ "developer", "api-created" ] } } }, "AllowSources": { "type": "array", "description": "Source configuration to allow via iptables.", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "IP address to allow connection.", "example": [ "0.0.0.0", "::" ] }, "netmask": { "type": "integer", "description": "Netmask to use with address for allowing connections.", "example": 0 }, "nic": { "type": "string", "description": "NIC name to accept connections on.", "example": "eth0" } } } }, "P12": { "type": "object", "description": "PKCS12 object with X.509 certificate and private key.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier to track the object on update since all the other fields are write-only. A random one will be assigned if left empty." }, "content": { "type": "string", "format": "byte", "writeOnly": true, "description": "Contents of the P12 file in Base64 format." }, "password": { "type": "string", "writeOnly": true, "description": "Password for the P12 file." }, "subjectName": { "type": "string", "readOnly": true, "description": "Subject name of the certificate in the file." } } }, "PrometheusExporter": { "type": "object", "description": "Prometheus Exporter configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Prometheus Exporter is enabled on this appliance or not.", "default": false }, "port": { "type": "integer", "description": "Port to connect for Prometheus Exporter.", "default": 5556 }, "allowSources": { "$ref": "#/components/schemas/AllowSources" }, "useHTTPS": { "type": "boolean", "description": "Whether to use HTTP or HTTPS for the exporter.", "default": false }, "httpsP12": { "$ref": "#/components/schemas/P12" }, "basicAuth": { "type": "boolean", "description": "Enable basic auth for Prometheus Exporter.", "default": false }, "allowedUsers": { "type": "array", "description": "Basic auth users.", "required": [ "username" ], "items": { "type": "object", "properties": { "username": { "type": "string", "example": "prometheus" }, "password": { "type": "string", "writeOnly": true } } } }, "labelsDisabled": { "type": "array", "description": "List of labels to filter out.", "items": { "type": "string", "enum": [ "collective_id", "collective_name", "appliance_id", "appliance_name", "appliance_version", "site_id", "site_name" ] } } } }, "Elasticsearch": { "allOf": [ { "$ref": "#/components/schemas/AwsBase" }, { "type": "object", "description": "Elasticsearch endpoint configuration on AWS.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the elasticsearch server.", "example": "https://aws.com/elasticsearch/instance/asdaxllkmda64" }, "retentionDays": { "type": "integer", "description": "Optional field to enable log retention on the configured AWS elasticsearch. Defines how many days the audit logs will be kept.", "example": 30 }, "compatibilityMode": { "type": "integer", "description": "Which version of Elasticsearch that logs are forwarded to.", "default": 6 }, "authentication": { "type": "object", "description": "Optional authentication settings used when sending logs to an elasticsearch instance.", "required": [ "type", "token" ], "properties": { "type": { "type": "string", "description": "The type of authentication to use.", "enum": [ "Basic", "ServiceAccounts", "TokenService", "ApiKeyService" ] }, "token": { "type": "string", "description": "The token to be used for authentication.", "writeOnly": true, "example": "user:password" } } } } } ] }, "TcpClient": { "type": "object", "required": [ "name", "host", "port", "format" ], "properties": { "name": { "type": "string", "description": "Name of the endpoint.", "example": "Company SIEM" }, "host": { "type": "string", "description": "Hostname or the IP address of the endpoint.", "example": "siem.company.com" }, "port": { "type": "integer", "description": "Port of the endpoint.", "example": 8888 }, "format": { "type": "string", "description": "The format to send the audit logs.", "enum": [ "json", "syslog" ] }, "useTLS": { "type": "boolean", "description": "Whether to use TLS to connect to endpoint or not. If enabled, make sure the LogForwarder appliance trusts the certificate of the endpoint." }, "filter": { "type": "string", "description": "JMESPath expression to filter audit logs to forward.", "example": "event_type=='authentication_succeeded'" } } }, "AwsKinesis": { "allOf": [ { "$ref": "#/components/schemas/AwsBase" }, { "type": "object", "required": [ "type", "streamName" ], "properties": { "type": { "type": "string", "description": "AWS Kinesis type", "enum": [ "Stream", "Firehose" ] }, "streamName": { "type": "string", "description": "Name of the stream.", "example": "Appgate_SDP_audit" }, "batchSize": { "type": "integer", "description": "Batch size for the stream. Used only for \"Stream\" type.", "default": 400 }, "numberOfPartitionKeys": { "type": "integer", "description": "Number of partition keys to use for the stream. Used only for \"Stream\" type.", "default": 10 }, "filter": { "type": "string", "description": "JMESPath expression to filter audit logs to forward.", "example": "event_type=='authentication_succeeded'" } } } ] }, "SumoLogic": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL of the Sumo Logic collector to connect to.", "example": "https://hostname.com/collector/677a49eb-da20-4143-ab61-cfd8aec64647" } } }, "Splunk": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL of the Splunk collector to connect to.", "example": "https://hec.hostname.com:443/services/collector/event" }, "token": { "format": "secret", "type": "string", "description": "Token to use for authentication.", "writeOnly": true, "example": "B5A79AAD-D822-46CC-80D1-819F80D7BFB" } } }, "AzureMonitor": { "type": "object", "required": [ "appId", "tokenRequestUrl", "logDestinationUrl", "scope" ], "properties": { "appId": { "type": "string", "description": "App ID to use for authentication." }, "appSecret": { "format": "password", "type": "string", "description": "App secret to use for authentication.", "writeOnly": true }, "tokenRequestUrl": { "type": "string", "description": "URL for Azure Monitor to request token from.", "example": "https://hostname.com/token" }, "logDestinationUrl": { "type": "string", "description": "URL of Azure Monitor to forward logs to.", "example": "https://hostname.com/logs" }, "scope": { "type": "string", "description": "Scope that the log forwarder will use in its tokens requests.", "default": "https://monitor.azure.com/.default" } } }, "FalconLogScale": { "type": "object", "required": [ "collectorUrl" ], "properties": { "collectorUrl": { "type": "string", "description": "URL of the Falcon LogScale collector.", "example": "https://api.humio.com" }, "token": { "format": "password", "type": "string", "description": "Ingest token.", "writeOnly": true }, "index": { "type": "string", "description": "Optional name of the repository to ingest into." }, "sourceType": { "type": "string", "description": "Translated to \\#type inside Humio. If set, this is used to choose which Humio parser to use for extracting fields." }, "source": { "type": "string", "description": "Translated to the @source field in Humio." } } }, "Datadog": { "type": "object", "required": [ "site", "apiKey", "source" ], "properties": { "site": { "type": "string", "description": "Datadog site to send logs to.", "example": "https://http-intake.logs.datadoghq.com" }, "apiKey": { "format": "password", "type": "string", "description": "API key to use for authentication.", "writeOnly": true }, "source": { "type": "string", "description": "Source to use for the logs.", "example": "appgate" }, "tags": { "type": "array", "description": "Tags to add to the logs.", "items": { "type": "string" }, "example": [ "appgate", "appgate-sdp" ] } } }, "Coralogix": { "type": "object", "required": [ "url", "privateKey", "uuid", "applicationName", "subsystemName" ], "properties": { "url": { "type": "string", "description": "URL of the Coralogix collector to connect to.", "example": "https://api.coralogix.com/api/v1/logs" }, "privateKey": { "format": "password", "type": "string", "description": "Private key to use for authentication.", "writeOnly": true }, "uuid": { "type": "string", "description": "UUID of the Coralogix collector to connect to.", "example": "12345678-1234-1234-1234-123456789012" }, "applicationName": { "type": "string", "description": "Application name to use for the logs.", "example": "appgate" }, "subsystemName": { "type": "string", "description": "Subsystem name to use for the logs.", "example": "appgate-sdp" } } }, "Kafka": { "type": "object", "required": [ "bootstrapServers", "authenticationType" ], "properties": { "topic": { "type": "string", "description": "Topic to publish logs to.", "example": "appgate-audit" }, "compression": { "type": "string", "description": "Compression codec to use when sending Kafka messages.", "enum": [ "gzip", "snappy", "lz4", "zstd" ] }, "bootstrapServers": { "type": "array", "description": "List of Kafka bootstrap servers (hostname or IP).", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "kafka.example.com" } }, "useTLS": { "type": "boolean", "description": "Whether to use TLS for Kafka connections.", "default": true }, "authenticationType": { "type": "string", "description": "Authentication mode used for Kafka.", "enum": [ "none", "basic", "token" ], "default": "none" }, "authorizationToken": { "format": "password", "type": "string", "description": "Authorization token used when authenticationType is token.", "writeOnly": true }, "username": { "type": "string", "description": "Username used when authenticationType is basic." }, "password": { "format": "password", "type": "string", "description": "Password used when authenticationType is basic.", "writeOnly": true } } }, "AllowResources": { "type": "array", "description": "A list of subnets to allow access.", "items": { "type": "object", "required": [ "address", "netmask" ], "properties": { "address": { "type": "string", "description": "IP address", "example": "0.0.0.0" }, "netmask": { "type": "integer", "description": "netmask", "example": 32 } } } }, "Portal": { "type": "object", "description": "Portal settings.", "properties": { "enabled": { "type": "boolean", "description": "Whether the Portal is enabled on this appliance or not.", "default": false }, "httpsP12": { "$ref": "#/components/schemas/P12" }, "httpsCiphers": { "type": "array", "description": "The type of TLS ciphers to allow. See: https://www.openssl.org/docs/man1.0.2/apps/ciphers.html for all supported ciphers.", "items": { "type": "string" }, "default": [ "TLS13-AES256-GCM-SHA384", "ECDHE-RSA-AES256-GCM-SHA384" ] }, "httpRedirect": { "type": "boolean", "description": "Automatic 80->443 redirection for Portal.", "default": true }, "proxyPorts": { "type": "array", "description": "Ports that can be proxied via Portal.", "items": { "type": "integer" }, "default": [ 443 ] }, "proxyP12s": { "type": "array", "description": "P12 files for proxying traffic to HTTPS endpoints.", "items": { "$ref": "#/components/schemas/portal12" } }, "profiles": { "type": "array", "description": "Names of the profiles in this Collective to use in the Portal.", "items": { "type": "string", "example": "Portal Users" } }, "externalProfiles": { "type": "array", "description": "Profiles from other Collectives to use in the Portal.", "items": { "$ref": "#/components/schemas/ExternalProfile", "properties": { "url": { "type": "string", "writeOnly": true, "description": "Appgate URL exported from Client Profiles.", "example": "appgate://appgate.company.com/eyJjYUZpbmdlcnByaW50IjoiMmM4ZTBiNTM5YTM4NjRkYmVkYzhiOWRkMTcwYzM0NGFhMjZjZTVhNjA4MmY3YTI0YzRkZTU4ZGQ3NWRjNWZhMCIsImlkZW50aXR5UHJvdmlkZXJOYW1lIjoibG9jYWwifQ==" } } } }, "signInCustomization": { "type": "object", "description": "Visual customizations to make on the Portal sign-in page.", "properties": { "backgroundColor": { "type": "string", "description": "Changes the background color on the sign-in page. In hexadecimal format.", "example": "#123456" }, "backgroundImage": { "type": "string", "format": "byte", "description": "Changes the background image on the sign-in page. Must be in PNG, JPEG or GIF format." }, "logo": { "type": "string", "format": "byte", "description": "Changes the logo on the sign-in page. Must be in PNG, JPEG or GIF format." }, "text": { "type": "string", "description": "Adds a text to the sign-in page." }, "textColor": { "type": "string", "description": "Changes the text color on the sign-in page. In hexadecimal format.", "example": "#123456" }, "autoRedirect": { "type": "boolean", "description": "If enabled and the user lands on the Portal sign-in page by entering an endpoint URL on the browser, it will be redirected to the endpoint automatically after successfully signing in instead of the Portal Client overview page." } } } } }, "Error": { "type": "object", "description": "Generic HTTP error.", "properties": { "id": { "type": "string", "description": "Machine readable error code." }, "message": { "type": "string", "description": "Human readable error details." } } }, "ValidationError": { "type": "object", "description": "Http 422 error for object validation.", "properties": { "id": { "type": "string", "description": "Machine readable error code." }, "message": { "type": "string", "description": "Human readable error details." }, "errors": { "type": "array", "description": "List of fields with validation errors.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Name of the field that failed validation.", "example": "name" }, "message": { "type": "string", "description": "Failure reason.", "example": "may not be null" }, "displayField": { "type": "string", "description": "Name of the field that should be displayed in the UI. It's an internal field to be used by the local replication service.", "example": "Name" }, "replicationMessage": { "type": "string", "description": "Message to be displayed in the replication UI. It's an internal field to be used by the local replication service.", "example": "Name is required." } } } } } }, "AwsBase": { "type": "object", "properties": { "awsId": { "type": "string", "description": "AWS ID to login. Only required if AWS Access Keys are being used to authenticate." }, "awsSecret": { "format": "password", "type": "string", "description": "AWS secret to login. Only required if AWS Access Keys are being used to authenticate.", "writeOnly": true }, "awsRegion": { "type": "string", "description": "AWS region. Only required if AWS Access Keys are being used to authenticate.", "example": "eu-west-2" }, "useInstanceCredentials": { "type": "boolean", "description": "Whether to use the credentials from the AWS instance or not." } } }, "portal12": { "allOf": [ { "$ref": "#/components/schemas/P12" }, { "type": "object", "properties": { "verifyUpstream": { "type": "boolean", "description": "Portal will verify upstream certificate of the endpoints.", "default": true } } } ] }, "ExternalProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier to track the object on update since all the other fields are write-only. A random one will be assigned if left empty." }, "hostname": { "type": "string", "readOnly": true, "description": "Hostname parsed from the given URL.", "example": "appgate.company.com" }, "profileName": { "type": "string", "readOnly": true, "description": "Profile name parsed from the given URL.", "example": "Main Profile" } } } }, "responses": { "JsonError": { "description": "JSON error. Check the JSON format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TokenError": { "description": "Token error. Login again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentError": { "description": "Insufficient license.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PermissionError": { "description": "Insufficient permissions to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFoundError": { "description": "The requested resource can not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "responses-NotAcceptableError": { "description": "Invalid 'Accept' header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Request validation error. Check \"errors\" array for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "UnexpectedError": { "description": "Unexpected server side error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBodies": { "Appliance": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Appliance" } } }, "description": "Appliance object.", "required": true } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } } } ````