API Tokens
Description
API token is a unique identifier of an application requesting access to your service, in this case, it is the Ambience software suite. Ambience would generate an API token for the application to use when requesting access to Ambience. Ambience can then match the token it provides to the one stored in the application in order to authenticate.
The API Tokens module provides a easy way to create an API token (randomly generated). The API token is assigned to a user and the Ambience modules that can be accessed by the application depends on the privileges that the user or owner has in Ambience. For example, if the user has access only to the dashboard module, the application with the API token can only access the dashboard module.
You can arrange/sort the list of API Tokens in ascending or descending order by clicking on the desired field. By default, the list is sorted by the “API Token” field in ascending order.
The basic features in this module are:
- Add API
- Edit API
- Delete
- Search
- Refresh page
This module is available for both Ambience and Repertoire software suite.
Module Interface
| Interface | Description | Required Privilege |
|---|---|---|
| API Tokens | Allows access to API Tokens page. | mod-api-tokens |
Add API Token
To add an API token, click on the “Add” button at the upper right corner of the page.
In the “Add API Token” dialog box will appear.
| Field | Description | Mandatory | Input Type | Default Value |
|---|---|---|---|---|
| User | Selects a user for the API token. | N | Drop-down list | None selected |
| Description | A brief description for the API token. | N | Text field | Empty string |
| Add Cookie | If selected, added cookie allow access to subsequent web requests after the initial request. | N | Checkbox | Not selected |
| Enabled | If selected, enables this API token. | N | Checkbox | Selected |
| Expires | Selects one of the three option how the API token will expire. Available options: - Never - After “a defined period” - At End of “current date” |
Y | Radio buttons | “Never” |
Select a user from the drop-down list in the “User” field. Only the user can use the API token. Key in a brief description for the API token in the “Description” field. By default, the new API token is enabled. If you wish to disable the new API token, unselect the “Enabled” field.
The “Add Cookie” field allows you to grant access to a web page (e.g., a form). Without the “Add Cookie” field being selected, the API token authenticates only one request. A web page loads many times from the server and these do not inherit the API token because they do not have the ?elx.token on the end. By selecting this field, the first call to the web page grants access (as before) but also registers a session cookie. Subsequent web requests will be authenticated as well. Together with an expiry being set, this allow users to temporarily access specific web pages with only one link, with no need for authentication.
On the right of the panel, you can determine the expiry of the token using the “Expires” field. You can choose to allow the token not to expire or expire after certain days/hours or after a certain date. By default, “Never” is selected.
Click on the “Save” button to save the API token. Clicking on the “Cancel” button aborts the action.
If the “User” field is not selected, an error message will appear.
The API token being generated (see “API Token” field), in this case, the API token is 154ef233-e40e-4e88-950c-08a509994dd1.
Edit API Token
This feature allows you change the user and description of the API token, as well as to enable or disable the token. To edit the API token, click on the 
“Edit” icon under the “Actions” column corresponding to the desired API token.
In the “Edit” panel, make the necessary changes and click on the “Save” button to save the changes. Click on the “Cancel” button to abort the action.
The API token if enabled, is indicated with a green tick under the “Enabled” column in the API Token Management page. A disabled API token is indicated with a red cross.
Delete
To delete an API token, click on the 
“Delete” icon under the “Actions” column corresponding to the desired API token.
There is an option to undo the deletion. A notification with an “Undo” button appears right after clicking on the “Delete” icon.
Upon clicking on the “Undo” button, the deleted API token is restored and is added back to the list of API tokens.
Refresh
After performing actions on the browser/tab, the list is reloaded to display the list of API tokens in the page. The manual “Refresh” button is available and is particularly useful if you or others have opened multiple pages and making changes.
The “Refresh” button is found at the upper right corner of the page. Clicking on it reloads the list.
Search
There is a cross-field search function for the list of API tokens. It is located at the upper left corner of the page.
This provides an easy way to search through the list of API tokens. It is case-insensitive and displays the API tokens that have the entered search value in any of the values of the fields below:
- API Token
- User
- Description
- Last Access
- Expires At
Alternatively, you can click on the “User” to aid the search for the records in the page.
In the example above, records that are assigned the user “admin” are shown.
These two search methods can be combined together, with each criteria separated by a comma.