API Tokens
Note: Ardexa hosts clouds in multiple regions as subdomains of ardexa.com. Where you see a reference to mycloud in this document, replace it with the appropriate subdomain for your cloud, eg: mycloud.ardexa.com -> app.ardexa.com or eur1.ardexa.com
Access to data and services hosted by the Ardexa Cloud can be granted via the Ardexa Frontend or via an Application Programming Interface (API). API access is used for applications, programs and scripts to automatically access Ardexa services. The Ardexa API uses token-based authentication & authorization to control user permissions programmatically. API tokens can be issued by users with the Manage Access permission. See the User and Permissions help page for more information.
Creating an API token
To create a new API token, click the "New token" button at the top of the API page.
API Tokens can be granted the same permissions as users, as described in Users and Privileges. The specific items for new tokens as as follows:
Token Owner: This is a free text field which should identify the owner of the token. The token owner is typically the person or organisation that has been issued with the token, not the person who has created it in the Ardexa Cloud. Name is recommended, but the entry can be anything you need.
Email Address: This field must contain a valid email address for the token owner. Expiry notifications will be sent to this email address when the token nears expiration.
Token expiry: This determines when the token will expire, and lose access to the system. Options are in 7 days, 14 days, one month, two months, three months, six months or one year's time.
Can renew: If selected, the token owner will be able to renew the token by calling the token renewal endpoint on the Ardexa API, see "Renew API token" below. This can be changed after the token has been issued to prevent further renewals of the token.
The following fields define the token's permissions. Once these have been set, they can not be changed:
Device Group: Optional feature to limit an API Token's access to only a subset of devices. Click here for more details.
Permissions: The API user is granted permissions in the same way as Ardexa Cloud users. See Users & Privileges for more information.
Once you are satisfied with the options you have selected, click "Generate token". This will display the token in the page, with the option to copy to your clipboard. After you have saved the token, click 'Done' to return to the API token list page.
Editing tokens
Tokens created under the new permissions system can be edited by clicking the 'Edit' button:
This allows you to update the token owner field, email address, enable / disable token self-renewal and alter the token expiry timeframe of future tokens.
Token permissions and device group cannot be edited. If your token owner needs different permissions, a new token will need to be issued.
Reissuing tokens
Tokens will lose access to the system once their expiry date passes. Reissuing a token generates a new token string with an updated expiry date and the latest settings attached to the token. To reissue a token, select "Reissue token" from the API token's drop-down menu:
The reissued token string needs to be sent to the API token user for them to retain access to the system. If they continue to use the original token string, they will lose access on the original token string's expiry date.
Revoking tokens
To revoke an API token, select 'Revoke token' from the token's drop-down menu. After confirming the revocation in a dialog, the token will lose access to the system, and will not appear in the API tokens view.
Revoked tokens can not be edited, reissued or otherwise have their access to the system restored. If a revoked token needs to be reinstated, you will need to create a new token with the same access to the system.
Selecting "Show revoked tokens" will display all tokens, revoked or active.
Guide: reducing an API token's permissions
Issuing an API token to a user gives them a level of access to the system until the token expires or is revoked. If a new token is issued to the user, they are still able to use the original token until it expires. If you need to reduce a token owner's level of access to the system, you will need to:
Create a new token with the desired level of access: remove permissions, set or change device group
Send the new token string to the user
Optionally, confirm that the new token has been deployed by the user
Revoke the original token
Issuing a new token with an increased level of access (more permissions or removing the device group restriction) does not strictly require the old token to be revoked.
Recommendations
API tokens should initially be issued for short time frames. This reduces the risks associated with the token being given to a new third party, eg. mishandling the token, relationship with the third party being terminated. Once the use of the token matures, the time frame can be extended.
Any permission granted to the API token should be the absolute minimum necessary to function correctly.
For standard data retrieval, the Read permission is sufficient.
Other permissions should only be granted if absolutely necessary. If you are unsure, please contact your Account Manager.
API token strings should be stored securely and should not be widely communicated.
Token Expiry
Ardexa will email notifications to workgroup owners and token owners when a token is nearing expiration. The notification sent to token owners will encourage them to use the Renew API token method, documented below, to renew the token if possible.
If token renewal is not possible, due to the token being expired, created with legacy permissions or renewal not being enabled, they will be encouraged to contact a workgroup owner.
Workgroup owners will receive a summary for all workgroups that they own, detailing each expiring & newly expired token.
If a token has expired, but is still displayed on the tokens page, it can be reissued by a user with the appropriate permissions.
Tokens that have been expired for more than four weeks will be removed from the system.
Renew API token
GET https://[mycloud].ardexa.com/api/v1/token/renew
Calling this endpoint with an API token will renew the token. The new token will have identical permissions and a new expiry time.
Headers
| Name | Type | Description |
|---|---|---|
authorization | string | Authentication token to be renewed. Format: "bearer: <token_to_renew>" |
Example: Renewing an API Token with cURL
Response
Last updated
