# Authenticate to the API

> Create an API key in the ITVA portal and send it as a bearer token with each request to the GraphQL API.

Section: API  
Source: https://www.itva.com/docs/api/authenticate-to-the-api  
Last updated: 2026-11-03

In this guide, you create an API key and use it to send your first request to the ITVA API. To learn how the API works, see [API overview](https://www.itva.com/docs/api/api-overview).

## Before you begin

- You can sign in to the ITVA portal.
- You know your API endpoint: `https://<INSTANCE_NAME>.itva.com/graphql/`.
- You have curl, or another HTTP client.

This guide creates a user API key, which acts as you. If the key is for an integration that must not depend on one person, use a system API key. See [Restrict API access](https://www.itva.com/docs/api/restrict-api-access).

## Create an API key

**Caution:** ITVA shows the token only once, in the dialog that opens when you save the key. After you close the dialog, ITVA shows only the first and last four characters.

1. Select your initials at the top right of the portal, then select **Settings**.
2. Under **General**, select **API Keys**.
3. Select **New API Key**. If you are an administrator, select **New User API Key**.
4. In **Name**, enter a name that says what the key is for. Each of your keys must have a different name.
5. Select **Save**. The **API Key Token** dialog opens.
6. Copy the **Token** and keep it in a safe place, for example a password manager or a secret store.
7. Select **Done**.

The token starts with `itva_`. It does not expire. It works until you delete the key, or until your membership is removed from the organization.

Anyone who has the token can use the API as you. Do not put the token in source code or share it in chat.

## Send the token with each request

Put the token in the `Authorization` header of each request, after the word `Bearer` and one space:

```
Authorization: Bearer <API_TOKEN>
```

This command sends a query that returns your name. Replace `<INSTANCE_NAME>` with the name in your portal address, and `<API_TOKEN>` with your token.

```sh
curl -X POST https://<INSTANCE_NAME>.itva.com/graphql/ \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "query": "query { me { name } }" }'
```

The **API Key Token** dialog shows the same command under **Sample**, with your endpoint and token already filled in.

In a script, read the token from an environment variable or a secret store. This Python example uses the `requests` library and reads the token from `ITVA_API_TOKEN`. It lists the first 10 devices and stops if the API returns an error.

`itva_devices.py`

```python
import os

import requests

QUERY = """
query Devices($limit: Int) {
  devicesPaginated(pagination: { offset: 0, limit: $limit }) {
    totalCount
    results {
      id
      name
    }
  }
}
"""

response = requests.post(
    "https://<INSTANCE_NAME>.itva.com/graphql/",
    headers={"Authorization": f"Bearer {os.environ['ITVA_API_TOKEN']}"},
    json={"query": QUERY, "variables": {"limit": 10}},
    timeout=30,
)
response.raise_for_status()
body = response.json()

if body.get("errors"):
    raise RuntimeError(body["errors"])

print(body["data"]["devicesPaginated"])
```

## Check that it worked

The curl command returns your name:

```json
{"data": {"me": {"name": "<YOUR_NAME>"}}}
```

If you use a system API key, `me` returns `ITVA System`, because a system API key does not belong to a person.

## Troubleshooting

If the response has an error with the code `UNAUTHENTICATED`, ITVA did not accept the token. Do these checks:

- Make sure the header is `Authorization: Bearer <API_TOKEN>`, with exactly one space between `Bearer` and the token.
- Make sure you copied the full token, from `itva_` to the last character.
- Open **Settings** > **API Keys** and make sure the key is still in the list.

If you get a redirect or an HTML page instead of JSON, make sure you send a POST to `/graphql/`, with the slash at the end.

If you lost the token, you cannot get it back. Create a new key, put the new token in your integration, then delete the old key.