SecurityGateway includes a REST API that lets external applications, scripts, and provisioning systems manage SecurityGateway programmatically instead of through the web interface. REST endpoints are rooted at https://<server>:<port>/api/v1 (the default HTTPS port is 4443), and every request must be authenticated with an API key. Successful responses follow a consistent {"success": true, "data": ...} shape, with a meta block added for paginated list results; failed requests return an HTTP error status along with a JSON body containing error, errorCode, and statusCode. The API covers most of the objects you can manage in the web interface plus read-only performance counters. The current release of the REST API covers: users, domains, domain aliases, administrators, API keys, server/domain/user settings, allowlists, blocklists, domain mail servers, user verification sources, DKIM selectors, archive stores, Sieve content-filter scripts, IP Shield entries, Dynamic Screening entries, and webhook subscriptions. More endpoints and capabilities will be added in future versions. The older XML-RPC API is still available, but new integrations should use the REST API going forward.
Programmatic resource requests use Authorization: Bearer <key>. The API Keys page, found at Setup/Users > Accounts > API Keys, is where you create and manage the keys used for this purpose.
The API Keys List
The API Keys page lists every key you have access to, and provides toolbar options for creating and managing them. The list has seven columns, with a corresponding button for each column that you can use to show/hide that column:
•Name - The descriptive name given to the key when it was created, to help you identify what it's used for.
•Owner - The user the key was created for, shown as that user's email address.
•Key Prefix - The first several characters of the key, shown so you can identify a specific key (for example, in application configuration) without needing to see the full key. The rest of the key is never displayed again after creation.
•Status - Shows whether the key is Active or Disabled. A disabled key still exists and can be re-enabled later, but is rejected if used to make an API request.
•Created - The date the key was created.
•Last Used - The date the key was last used to successfully authenticate an API request. It displays "Never" if the key has never been used.
•Expires - The date the key will stop working, if an expiration date was set when it was created. It displays "Never" for keys that do not expire.
Create Key
Opens the Create API Key dialog, described below, to generate a new key.
Disable
Disables the selected key or keys. A disabled key remains on this list and can be re-enabled at any time, but cannot be used to authenticate API requests while disabled.
Enable
Re-enables the selected key or keys, restoring their ability to authenticate API requests.
Delete
Permanently deletes the selected key or keys, after asking you to confirm. Unlike disabling a key, this cannot be undone. A deleted key cannot be restored or re-enabled, and a new key would need to be created in its place.
Who Can See Which Keys
What you see on this page depends on your own administrator level. Global administrators see every API key in the system, and can narrow the list to a specific domain or user. Domain administrators see the keys belonging to users in the domains they administer, plus their own personal keys. They cannot see keys belonging to domains they do not administer, or keys belonging to other global administrators. Global administrators and domain administrators can manage their own keys on the Main > My Account > Settings page.
Click Create Key to open a dialog with the following options.
Name
A required, descriptive name for the key (for example, "Provisioning Script" or "Monitoring Integration"), so you can tell your keys apart later. This is the same value shown in the Name column on the API Keys list.
Expiration Date
An optional date after which the key will stop working. Leave this blank if you don't want the key to expire.
Permissions
This section is informational rather than a setting you configure directly. A new API key is always created with the same access as the account creating it. If you are a global administrator, the key will have global administrator access. Otherwise, the key will have the same permissions as your own account. There is no option to create a key with narrower or broader permissions than your account currently has.
|
A key's access is checked against the owning user's current permissions every time it's used, not the permissions that user had when the key was created. If you later promote or demote the key's owner, restrict their administrator permissions, or change which domains they administer, every API key that user owns immediately reflects that change. Disabling the owning user's account also blocks every API key belonging to that user, even if the keys themselves are still marked Active. Deleting an account will also delete all of that account's API keys. Admin IP restrictions apply to API keys the same way they apply to web logins. If the key's owning user is an administrator with an IP address restriction configured, requests made with that key from a disallowed IP address are rejected, just as a web login attempt would be. |
Save
Once you have set your key name and expiration date, click Save to display your key for copying.
Your API Key
After you click Save, SecurityGateway generates the key and displays it exactly once, along with a warning that you will not be able to see it again. Click Copy to copy it to your clipboard. You should then store it in a secure location. If you close the dialog without copying it, SecurityGateway will ask you to confirm, since there is no way to retrieve the key afterward; only its prefix remains visible on the API Keys list. If you lose a key, the only way to recover access is to create a new one and update whatever application was using the old key. The dialog also shows the format expected when using the key in the authorization header. Programmatic resource requests use Authorization: Bearer <key>. Successful responses generally contain data, but some successful mutations, such as delete, return a message without it.
API Documentation
The full REST API reference, along with a getting-started guide and the legacy XML-RPC documentation, is installed locally in the Docs\API folder under the SecurityGateway installation directory — you don't need network access to the running server to read it.
README.md
A quick-start guide covering the base URL, authentication, response and error formats, and a migration guide for existing XML-RPC integrations, including a method-to-endpoint mapping table and worked examples for creating a domain, updating a user, and reading and writing settings.
api_openapi.html
A browsable, human-readable copy of the complete API reference.
api_openapi.json
The machine-readable OpenAPI specification backing that reference, suitable for import into tools such as Postman or for use with OpenAPI-aware code generators. This is the same file served at /api/v1/openapi.
XMLRPC
Reference documentation and working code samples (PowerShell and Python) for the older XML-RPC API, kept for administrators maintaining existing XML-RPC integrations. XML-RPC is deprecated; new integrations should be built against the REST API described above, using the README's migration guide as a starting point.
