To get authenticated for using the Versio.io API, you need a valid API token. Access to the API is fine-grained, meaning that you also need the proper permissions assigned to the token. See the description of each request to find out which permissions are required to use it.
Generate API token
You can assign multiple permissions to one single token or you can generate several tokens, each with different access levels.
Please note that it is very helpful to use meaningful names for the API token. This makes the later management (activate/deactive, delete) of the API Token easier.
With the following steps an API token can be created:
- Select Environment settings in the left navigation main menu.
- Go to section Access management -> Tab 'API token'.
- Enter a descriptive name for the API token.
- Select the required permissions for the API token.
- Click the Generate button to create a new API token with selected permissions.
- In the section My API Token you will now find the newly created API Token. Open the corresponding line to see the token and the assigned permissions.
The following figure shows the user interface for creating and managing the user-specific API tokens:
Figure: Create a new user specific API token
Management API token
With the appropriate authorization, a user can also manage the API tokens of other users in the environment. This includes deactivating/activating and deleting the API tokens. The following figure shows the corresponding user interface:
Figure: Manage the API tokens of the logged on user and all other users in the environment
Use of API Tokens
Authenticate the API usage by attaching the token to the authorization HTTP header preceding the API token realm.
curl --request GET \ --url https://live.versio.io/api-versio.db/1.0/my-environment \ --header 'Authorization: api-token 8as7bf9a8s7498svaps8dfabsf'
Example: API request with an API token in the HTTP request header
Authenticate API usage by adding the API token as a query parameter.
curl --request GET \ --url 'https://live.versio.io/api-versio.db/1.0/my-environment?api-token=8as7bf9a8s7498svaps8dfabsf'
Example: API request with an API token as HTTP query parameter