Skip to content

API authentification

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:

  1. Select Environment settings in the left navigation main menu.
  2. Go to section Access management -> Tab 'API token'.
  3. Enter a descriptive name for the API token.
  4. Select the required permissions for the API token.
  5. Click the Generate button to create a new API token with selected permissions.
  6. 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:

Create a new API token

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:

Create a new API token

Figure: Manage the API tokens of the logged on user and all other users in the environment

Use of API Tokens

HTTP header

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: apiToken 8as7bf9a8s7498svaps8dfabsf'

Example: API request with an API token in the HTTP request header

Query parameter

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?apiToken=8as7bf9a8s7498svaps8dfabsf'

Example: API request with an API token as HTTP query parameter