Skip to content

API Tokens

An API token represents an authentication and an authorization mechanism for 3rd party scripts and applications to communicate with the software using its REST API. After being created in the software, an API token generates a unique string signed by the tenant signature key in a standard JSON Web Token (JWT) format that defines a compact and self-contained way for securely transmitting information from external parties to the software's server.

Use JWT tokens as a Bearer token in the Authorization header of HTTPS REST API request for the software API. The example below demonstrates a call for the /user/me function of the software API for the server accessed, using URL given by the variable URL and the JWT token given by the variable TOKEN.

curl -i "$URL/api/user/me" -H "Authorization: Bearer $TOKEN"

The REST API is used to access and manage system data and processes as well as to trigger system events. Every operation that could be performed using the software's WEB Portal GUI has a corresponding set of REST APIs. We encourage you to review and try the OpenAPI documentation about the software's REST API by accessing the API Documentation link on the bottom of the My Profile > About page.

Creating API Tokens

To create an API Token:

  1. Log in with an Administrator or API Token Manager account.
  2. Navigate to Management > API Tokens and click the Add button.
  3. Click on the parameter name for details about each or follow the guidance provided here:
    1. User: is a system user. After successful validation of the signature of the JWT token received from a 3rd party application, the server uses this user, encoded in the JWT token, to generate authorization roles of the caller to the system objects and operations. In case the caller does not have the required permission to the system objects or operations, the system does not authenticate the call.
    2. Expire: is the time after which the system will not validate a JWT token for successful authentication.
    3. Filter: is the IP address or IP address range where the caller should be located for a successful authentication.
    4. Description: is a comment about the API token use in the software deployment.
    5. Enabled: is an indicator that allows successful authentication of a JWT token.
  4. Click the Save button to complete the operation.

To access and copy a JWT Token:

  1. Log in with an Administrator account.
  2. Navigate to Management > API Tokens and expand the entry you want to view or copy the token from using its expansion arrow (Show Details) under the Actions column header.
  3. From the JWT field, click the Unlock Token button to unlock the field which will also generate a new JWT token. Once unlocked, you can:
    1. Copy: this option will copy the JWT token to your clipboard without making it visible on your screen.
    2. Show Token: this option will display the JWT token in this field. You may manually copy this value once visible.
    3. Lock Token: this option will return the JWT field to its original locked state. Collapsing this entry or navigating away from this page will result in an automatic lock action.

API Token Unlock Button

Managing API Tokens

Administrators and API Token Managers can manage existing API tokens by using the available options from within the Actions menu:
* Edit: the Edit option allows the API token parameters to be modified, including User, Name, Description, Filter, Expires and Enabled status.
* Delete: the Delete option will delete this token from the software. This operation cannot be undone. If the token should remain for historical value, we would recommend expiring the token rather than deleting it.

API Token Actions Menu