Enabling and managing SMC's public API

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 .

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.

The public API and its documentation use port 443 by default.

The default port can be changed by modifying the environment variable SMC_PUBLIC_API_PORT_INT:

1. Log in to the SMC server via the console of your hypervisor or in SSH.
2. In the file /data/config/fwadmin-env.conf.local, add the environment variable SMC_PUBLIC_API_PORT_INT="portNumber".
3. Restart the server with the command nrestart fwadmin-server.