# API authentication

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/deactivate, delete) of the API Token easier.

An API token can be created with the following steps:

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](<https://docs.versio.io/img/settings/api-token/setting-api-token-generation.png>)

*Figure: Create a new user-specific API token*

## Manage API tokens

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](<https://docs.versio.io/img/settings/api-token/setting-api-token-management.png>)

*Figure: Manage the API tokens of the logged-in 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, preceded by the `apiToken` realm.

```text
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.

```text
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*
