Enabling and managing SES Evolution's public API

SES Evolution has a standard REST API with which the solution can be used through your own orchestration tools.

Some SES Evolution features are not yet available in the public API. It will be enriched along with every new version.

The public API is not enabled by default.

Authentication over the public API is secured by API keys that administrators generate. The usage and validity of these keys can be configured.

POST operations performed via the public API are recorded in system logs.

To facilitate the use of the API, you can access OpenAPI documentation through a link shown in the administration console. It can also be found on Stormshield's Technical Documentation website.

You need to hold the Public API-Modify permission to enable the public API and generate keys from the API keys menu in the administration console. See Managing users on the SES Evolution administration console.

This permission has priority over the System permission. If an administrator does not hold any System permissions, but holds the Public API-Show or Public API-Modify permission, the System menu will appear with only the API keys tab.

SES Evolution's public API is disabled by default.

When the public API is enabled:

  • Access to routes on the API is allowed,

  • Authorized administrators can create, modify and revoke API keys.

To enable the public API:

  1. In Backoffice > system, show the API keys tab.

  2. Click on Edit in the upper banner.

  3. Select Enable Public API.

    API keys tab

The API keys tab makes it possible to add, modify and revoke keys that grant access to SES Evolution's public API routes.

These keys have an ID, description, creation date, expiry date and usage. They are required for every public API request.

To add a key:

  1. Click on Edit in the upper banner.

  2. Click on Add an API key.

  3. Enter a description.

  4. Select a validity duration. Once the key has been created, you will no longer be able to modify this duration.

  5. Check the usage of the key, which open access to the various routes offered by the API.

  6. When you click on OK, the key will not be saved in the database. It must be copied and stored in a safe place as it will no longer be available later.

  7. Click on Close, then on Save in the upper banner.

All SES Evolution administrators who are allowed to display the API keys tab have access to the list of keys created.

API keys can be used in API documentation to test requests:

  1. Click on the See API documentation link.

  2. Click on the button .

  3. Enter the API key in the Value field.

  4. Click on Authorize then on Close.

API keys can be revoked. Once they are revoked, you can no longer use them to submit requests on the API.

To revoke a key:

  1. Click on Edit in the upper banner.

  2. On the line of the key to revoke, click on the icon in the Actions column.

  3. Confirm.

If you wish to display only unrevoked keys in the table, enable the Hide revoked keys button.

The public API documentation does not appear

Situation: The See API documentation link in the administration console opens a web browser and the documentation does not appear.

Cause: If you have upgraded SES Evolution to version 2.6.3 and your backend server is installed on the Windows Server 2022 operating system, the TLS 1.3 option is enabled by default in the backend IIS settings. This option makes the API documentation incompatible with this operating system.

Solution: In your IIS service manager, disable the TLS 1.3 over TCP option in the settings of the backend host name. The host name to be modified can be seen in the URL of the API documentation, which corresponds to the host name of the backend used when SES Evolution was installed.