Every API request must include an authentication code that identifies and authenticates the user against the proper realm within the platform. This is identified in the API call as the password (pwd or p) and is used for the FTP, Rest, and HTTP APIs. The WebServices API uses a generated key passed in the commands to authenticate.
In addition the simple default authentication, a new level has been created to provide the ability to restrict access to specific API users in a Realm based on a grouping defined as API Client. Each Realm can create up to five API Clients (including the default client), and provide the API Client authentication code along with the API Password to the API users. You may choose to create an API Client based on the type of API in use (such as HTTP vs. FTP), business unit (such as department or region), or by third-party access (such as external vendors or contractors).
If your Realm is already enabled to use APIs, your Default API Client will continue to work as it did previously, without requiring any updates to your currently running integrations. With the addition of API Clients, you can now create four more API Clients to control which has access to your Realm at any time.
Enabling the API
Before using the APIs in your Realm, API access must be enabled. To do this, please contact your Customer Support Specialist.
Once API access has been enabled, you can manage the API Clients in the Customer Center at CUSTOMER CENTER > API MANAGEMENT > SETUP API.
When API access is enabled for a realm, a default client already exists. The Default Client does not require an additional Client Authentication code in the API commands, and you can generate the WebServices License File and API Password for Rest, HTTP, and FTP APIs.
Creating an API Client
To create a new API Client:
- Go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.
- From the API Client listbox, select Add New API Client.
- Enter a Name with no spaces or special characters. API Client names should be alphanumeric only.
- Enter the Purpose of the API Client as a string.
- If you wish to restrict access by IP, enter the IP(s).
- Click SAVE.
In order to use the Client in API calls, generate the API Client authentication code. To do this:
- Next to Client Password, click GENERATE AUTHENTICATION CODE.
- In the modal, click YES to continue.
- Copy the red authentication code.
Once the modal closes, this code cannot be retrieved. If you misplace the code, you must generate a new code. Please note that generating a new code will invalidate the current code for anyone using the API Client.
After the API Client authentication code is generated, you can generate the WebServices License File and the API Password for HTTP and FTP APIs.
Generating Webservices API License
To use the WebServices API, you must have a key. The same process works for any API Client. However you cannot generate the License File until after the API Client Authentication Code has been generated in API Clients other than Default. For the WebServices API:
- Click GENERATE LICENSE FILE.
- In the modal, click YES to continue.
- The license key will display in a modal and a copy will be sent to your email address.
If you misplace the key, you must generate a new key. Please note that generating a new key will invalidate the current key for anyone using the Webservices API. If you attempt to generate a key before the API Client authentication code, an error will occur.
Generating API Password for APIs
To use the Default Client in the REST, HTTP, and FTP APIs, you must have an API Password. The same process works for any API Client. However you cannot generate the API Password until after the API Client Authentication Code has been generated in API Clients other than Default. For these APIs:
- Click GENERATE API PASSWORD.
- In the modal, click YES to continue.
- The API password will display in a modal.
If you misplace the password, you can retrieve it from the API Client Management page. Please note that generating a new password will invalidate the current password for anyone using these APIs. If you attempt to generate a password before the API Client authentication code, an error will occur.
Restricting Access via IP
As added security, you can limit API access to certain systems in your network. To do this:
- Go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.
- Select an API Client.
- Enter the IP address in Restrict IP Address. Separate multiple addresses with commas, spaces or semicolons. To support a range of addresses, enter the IP range. For example, to restrict access through the API to one system at 216.39.173.94, enter that address directly. To allow access from any system on the .173 network, enter only 216.39.173.
- Click SAVE.
Suspending a Client
To prevent API access through the API Client, disable access using the Suspend option. To suspend an API Client:
- Go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.
- Select an API Client.
- Select the SUSPEND checkbox.
- In the modal, enter a reason for the suspension, then click SUSPEND.
The options to generate authentication are disabled and the reason of the suspension is displayed next to the Suspend option. Any API calls that use the API Client and authentication will report FAILURE.
Activating a Suspended Client
To allow access to a suspended API Client:
- Go to CUSTOMER CENTER > API MANAGEMENT > SETUP API.
- Select an API Client.
- Deselect SUSPEND.
- In the modal, click YES to continue.
The options to generate authentication are enabled. Any API calls that use the API Client and authentication will now work as expected.
Deleting a Client
To delete an API Client, you must first suspend it. Once the API Client is suspended, click DELETE. In the modal, click DELETE to continue.
The API Client will no longer be available to select. Any API calls that use the API Client and authentication will report FAILURE.