Authenticate to the API

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.

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.

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.

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.

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:

{"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.