Restrict API access

An API key can do only what its access allows. This guide explains the two kinds of API key, then shows you how to create a system API key with limited access.

User and system API keys

A user API key always has the same access as its creator. If an administrator creates a user API key, the key has administrator access. You cannot limit a user API key to less than its creator can do.

Administrators cannot see or delete another person's user API keys. To stop all of a person's user API keys, remove that person's membership.

For an integration, use a system API key. It keeps working when people leave, and you can give it less access than any person has.

How permissions apply to an API key

API keys follow the same access rules as people. For the full rules, see Access control overview. In short:

• A key with administrator access can view and change everything in your organization.
• Other keys get access through permissions. A permission is a role plus tags. The role says which actions are allowed. The tags say which items the role applies to.
• If a key has more than one permission, ITVA adds them together.
• For item types limited by tags, such as devices, the key can use only items that have at least one of the permission's tags.

ITVA reads a key's access on each request. If you change a key's permissions, or change a role that the key uses, the change applies to the next request.

Before you begin

• You must be an administrator.
• A role exists that allows only what the integration needs. See Roles and permissions.
• The items the integration uses have tags. See Use tags.

Create a system API key with limited access

Caution: ITVA shows the token only once, in the dialog that opens when you save the key.

1. Select your initials at the top right of the portal, then select Settings.
2. Under General, select API Keys.
3. Select New System API Key.
4. In Name, enter the name of the integration that will use the key.
5. Keep Administrator turned off.
6. Under Permissions, select Permission (the button with a plus icon) to add a row.
7. In the role list, select the role.
8. Select Tags. In the Select Tags panel, select each tag the role applies to, then select Select. To add another permission, repeat steps 6 to 8.
9. Select Save. The API Key Token dialog opens.
10. Copy the Token and keep it in the secret store that the integration reads from.
11. Select Done.

Change or remove a key's access

To change a key, open Settings > API Keys, select the key, then select Edit API Key. For a system API key, you can change the name, Administrator, and the permissions. For a user API key, you can change only the name.

To revoke a key, open the key, select Delete, and confirm. ITVA stops accepting the token at once.

Tokens do not expire. To replace a token, for example on a schedule or after someone sees it, do these steps:

1. Create a new key with the same access.
2. Put the new token in the integration.
3. Make sure the integration works with the new token.
4. Delete the old key.

Check that it worked

• Open the key in Settings > API Keys. Administrator shows No, and Permissions shows each role with its tags.
• Send a devicesPaginated query with the new token, as in Authenticate to the API. The results include only devices with the key's tags, or in folders with those tags.

Troubleshooting

If you see the error At least one permission is required for non-administrator API keys., add a permission row, or turn on Administrator.

If New System API Key is not on the API Keys page, you are not an administrator. Ask an administrator to create the key.

If the key cannot see an item, make sure the item has one of the tags in the key's permission. Also make sure the permission's role has View set to All for that resource.

If the key creates an item and then cannot see it, the item has none of the key's tags. Give the item one of the key's tags when you create it.