Getting Started¶
The API is intended to be used for machine-to-machine communication and system integration.
Access tokens¶
Authentication with the API needs to be done using an access token. To issue a new token, navigate to the "Access token" dialog using the button on the bottom-left corner. Here, all active access tokens can be viewed, and new ones issued.
When issuing a new token, the following fields must be specified:
- Name: A human-readable name used to identify the token.
- Expiration date: The date after which the access token will automatically stop working.
- Scopes: Permissions that the token will have. These take the format of
<action>_<resource>. Where an action is eitherreadorwrite.
Note
Access tokens inherit all role- and application- permissions from the user who issued it. When used, the token acts on behalf of that user.
Immediately after creation of an access token, its value will be displayed. Make sure to save it somewhere safe. After you leave the page, you no longer have access to the token. The token takes the form of a JSON Web Token (JWT) and needs to be included on all requests in a HTTP header:
Authorization: Bearer <access token>
Warning
Access tokens must be treated carefully. Do not store tokens in plaintext in your projects. Use minimal scopes if possible, and set a short expiration date fitting your use-case.
If a token is no longer required, or if it has been compromised, it can be revoked. This will immediately block any requests being authenticated with that token.