Enabling and managing SMC's public API

SMC has a standard REST API with which your SMC servers can be used and queried through your own orchestration tools.

All SMC features are not yet available in the public API. It will be enriched as new versions are released.

The public API is not enabled by default. Only the SMC super administrator can enable it.

Authentication over the public API is secured by API keys that administrators generate. These keys have read/write or read-only privileges as well as a validity period that can be configured.

All operations performed via the public API are recorded in audit logs.

To make it easier to use the API, OpenAPI documentation is available on the SMC server through the address https://<@SMCIP>/docs/papi or via the link shown in the SMC web interface.

Documentation can also be found on Stormshield's Technical Documentation website.

NOTE
In case of intensive use of the API, i.e., several write requests within a few seconds, while other users are using the administration web interface at the same time, the performance of SMC may be impacted. Some requests may fail.
Likewise, if you plan a regular intensive use, we recommend that you disable configuration consistency checking to avoid impacting SMC performance. For more information, see the section Verifying configuration consistency.

SMC's public API is disabled by default.

Only the super administrator can enable or disable it from the SMC web administration interface.

When the public API is enabled:

  • access to routes on the API is allowed,

  • access to documentation about the API is allowed,

  • the super administrator can grant permissions to create and revoke API keys to other administrators,

  • administrators with the relevant privileges can create and revoke API keys.

To enable the public API:

  1. In Maintenance > SMC server, show the Public API tab,

  2. Select Enable Public API.

The Public API tab displays the API keys created by other administrators. The super administrator cannot create API keys, but can revoke them. For more information on revoking keys, refer to Revoking API keys.

An API key is required for authentication on a public API. Administrators can create API keys in the SMC web administration interface, by setting read/write or read-only permissions for the keys, as well as an expiry date. For more information on creating keys, refer to Creating API keys.

The API keys created must be added to the Authorization header in each API request.

EXAMPLE OF AN API REQUEST
In command line: curl -H "Authorization: Bearer <API_KEY>" https://<IP_SMC>/api/v1/firewalls

Permissions to create and revoke API keys are granted by the super administrator, in administrators' profiles.

NOTE
The super administrator cannot create API keys.

To grant an administrator permissions to create and revoke API keys:

  1. In Maintenance > SMC server, show the Administrators tab,

  2. Double-click on the profile of an administrator,

  3. Select API keys creation/revocation in Access privileges.

This option is grayed out if the public API is disabled.

The super administrator can set a default validity period for API keys. When another administrator creates a key, the validity period set by the super administrator will then be suggested by default in the Expiry date field, which the administrator can edit.

To edit the API key global policy:

  1. In Maintenance > SMC server, show the Public API tab,

  2. Click on Edit the API key global policy.

  3. Set the validity period suggested by default to administrators when they create a key, and apply. This period cannot exceed 25 years.

Administrators who hold the API keys creation/revocation privilege can create the API keys to use for authentication on the public API. For more information on this privilege, refer to Allowing administrators to create and revoke API keys.

These keys contain an ID, name, expiry date and read/write or read-only permission. They are required for every public API request.

To create a key:

  1. In Maintenance > SMC server, show the API keys tab. Keys that have already been created will be listed along with their information.

  2. Click on Add a key.

  3. Enter a name and expiry date. The default validity period is set by the super administrator. For more information, refer to the section Editing the API key global policy.

  4. In the Usage field, select the desired option. You cannot select Write if you do not hold this permission yourself in SMC as an administrator.

  5. When you click on Apply, 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.

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

  1. Click on the See API documentation link in the API keys tab in Administrator view, or in the Public API tab in Super administrator view.

  2. Click on Authorize button.

  3. Enter the API key in the Value field.

  4. Click on Authorize then on Close.

When the profile of an SMC administrator is deleted, API keys associated with this administrator will be automatically deleted if they had been revoked earlier. For more information on revocation, see the next section.

The super administrator can revoke all API keys and administrators can revoke the API keys that they created themselves. When API keys are revoked, you can no longer use them to submit requests on the API.

As super administrator:

  1. In Maintenance > SMC server, show the Public API tab,

  2. Select the key to revoke in the grid,

  3. Click on Revoke.

As super administrator, if you wish to delete the profile of an administrator, you must first revoke the API keys associated with them. Profiles cannot be deleted if the administrator still holds active keys.

Similarly, an administrator's Read/Write privilege in SMC cannot be withdrawn if this administrator holds active API keys that also have the Read/Write privilege. The keys in question must be revoked first.

As administrator:

  1. In Maintenance > SMC server, show the API keys tab.

  2. Select the key to revoke in the grid,

  3. Click on Revoke.