> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/user-management/authorization/api-keys.md).

# API Keys

Use API Keys for production integrations and automation that need stable ThousandEyes API access for non-human workflows. An API Key belongs to your organization, not to an individual user, so the credential is not affected when a user changes roles or leaves the organization.

## Choosing an API Credential

| Scenario                                                          | Recommended credential                                                                                                                    | Why                                                                                                             |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Production integrations, automation, and service-owned workflows. | API Key                                                                                                                                   | The credential is organization-owned, can be scoped to the integration's job, and can be rotated independently. |
| Separate tools, workflows, or environments.                       | One API Key for each integration.                                                                                                         | Each key has its own permissions, account group access, and lifecycle.                                          |
| Testing, exploration, and individual ad hoc requests.             | [OAuth bearer token](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#user-api-tokens) | The credential is user-owned and uses the user's permissions.                                                   |

## Required Permissions

The **API Keys** tab is available to users with the *Manage own API Keys* permission or the *Manage all API Keys in organization* permission.

The built-in Organization Admin role includes both permissions. The built-in Account Admin role includes *Manage own API Keys*. The built-in Regular User role does not include either permission by default. You can assign one or both permissions to custom roles.

Users with *Manage own API Keys* can create API Keys and manage only the keys that they created. Users with *Manage all API Keys in organization* can view and manage all API Keys in the organization, including keys created by other users.

If the user who created a key leaves the organization, a user with *Manage all API Keys in organization* can continue to manage that key.

When you create an API Key, you can assign only account groups and permissions that you already have. To create a key that can access all account groups, your own access must include all account groups in the organization.

{% hint style="info" %}
API Keys include the *API access* permission by default. You do not select or remove this permission when you select a key's permissions. API Key management permissions authorize users to manage API Keys, and are not available in the API Key permission selector.
{% endhint %}

## Selecting Permissions

Give each key only the account group access and permissions that its integration needs. If an integration only reads data, start with view permissions. Add edit, create, run, or delete permissions only when the integration calls endpoints that change resources.

When you create a key, select an account group before you select permissions. The permission picker groups permissions by functional area, such as **Administration**, **Alerts**, **API**, **Endpoint Experience**, and **Tests**. Expand the category that matches the API resources your integration uses, or use the search field to find a permission by name.

For descriptions of permissions that also appear in role configuration, see [Built-In Roles and Permissions](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/built-in-roles-and-permissions).

## Creating an API Key

1. Go to **Manage > Account Settings > Users and Roles > API Keys**.
2. Select **Create API Key**.
3. Type a name that helps you identify the key. This name is the key's primary identifier in API Key lists and detail screens.
4. In **Account Group**, select the account group that the key can access. If **All account groups** is available and the key needs organization-wide access, select **All account groups**.
5. In **Permissions**, select the permissions for the selected account group.
6. To give the key access to another account group, select **Add account group**, then select the account group and permissions.
7. In **Default account group**, select the account group that ThousandEyes uses when an API request does not include the `aid` query parameter.
8. Select **Next**.
9. Complete multifactor authentication (MFA) verification by entering the verification code sent to your email address.
10. Select **Next**.
11. Copy the full key value and store it securely, or select **Copy & Close** to copy the key value and close the screen.

{% hint style="warning" %}
The API Key is displayed only once when you create or regenerate it. Copy and store the key securely before closing the screen. ThousandEyes cannot show the same key value again after you leave the creation or regeneration screen.
{% endhint %}

## Viewing API Keys

The **API Keys** tab shows each key's name, key prefix, expiration date, created account, and status. The status can be active, inactive, or expired.

To open the API Key detail screen, select the key name. You can also select the row actions menu, then select **View detail**.

Use the API Key detail screen to view the key's creator, default account group, expiration date, and permissions for each account group. You can also delete or regenerate the key from this screen.

## Using an API Key

To authenticate an API request, send the API Key in the `Authorization` header:

```bash
curl https://api.thousandeyes.com/v7/tests \
  --header "Authorization: Bearer <api-key>"
```

If the key can access multiple account groups, use the `aid` query parameter to select the account group context for the request:

```bash
curl "https://api.thousandeyes.com/v7/tests?aid=<account-group-id>" \
  --header "Authorization: Bearer <api-key>"
```

If you omit `aid`, ThousandEyes uses the key's default account group.

## Regenerating an API Key

Regenerate a key before it expires, when it has been exposed, or when your credential-management process requires rotation. Regeneration keeps the same name, account group access, and permissions, and returns a new key value.

After regeneration, both the previous and new key values are active for seven days. During that grace period, update every integration that uses the previous key value. After seven days, the previous key can no longer authenticate requests.

You cannot regenerate the key again until the grace period ends.

To regenerate a key in the UI:

1. Go to **Manage > Account Settings > Users and Roles > API Keys**.
2. Open the API Key detail screen by selecting the key name, or by selecting the row actions menu and then **View detail**.
3. Select **Regenerate**.
4. Complete MFA verification by entering the verification code sent to your email address.
5. Copy the new key value and store it securely.
6. Update every integration that uses the previous key value.

To regenerate a key with the API, authenticate the request with the API Key that you want to regenerate:

```bash
curl --request POST https://api.thousandeyes.com/v7/api-keys/regenerate \
  --header "Authorization: Bearer <api-key>"
```

OAuth bearer tokens and other API Keys cannot regenerate a key through this endpoint.

## Disabling or Deleting an API Key

Disable a key when you need to stop an integration temporarily without deleting the key. An inactive key cannot authenticate API requests. You can enable the key again when the integration is ready to resume.

Delete a key when the integration no longer needs ThousandEyes API access. Deletion is permanent. After you delete a key, it cannot authenticate API requests and cannot be recovered.

To disable a key, turn off the status toggle in the **API Keys** table, then confirm the action. To enable the key again, turn on the status toggle.

To delete a key in the UI:

1. Go to **Manage > Account Settings > Users and Roles > API Keys**.
2. Open the API Key detail screen by selecting the key name, or by selecting the row actions menu and then **View detail**.
3. Select **Delete**.
4. Complete MFA verification by entering the verification code sent to your email address.
5. Select **Delete**.

You can also start the delete flow by selecting **Delete** from the row actions menu.

## Reviewing Activity

Use the **Activity Log** to review API Key creation, regeneration, and deletion events. Enable and disable events are not shown in the **Activity Log**.

## Managing Expiration

API Keys expire after 180 days. Regenerate a key before it expires so the integration can continue to authenticate. ThousandEyes sends expiration reminders for active keys before they expire. Reminders go to Organization Admins and to the user who created the key.

## Limits and Considerations

* Each organization can have up to 25 API Keys.
* If your organization reaches the API Key limit, the **Create API Key** button is disabled.
* You cannot change a key's name, permissions, or account group access after creation. To change a key's access, create a replacement key, update your integration, and then delete the old key.
* Custom expiration periods are not supported. If your organization requires a shorter rotation cycle, automate API Key regeneration on your preferred schedule. Schedule rotations more than seven days apart because you cannot regenerate the same key during the grace period.
* IP allowlisting for API Keys is not supported.
* API Keys share your organization's API rate limit, which is typically 240 requests per minute.

## API Reference

You cannot create an API Key with the API. The API supports regenerating the authenticating API Key with [`POST /v7/api-keys/regenerate`](https://developer.cisco.com/docs/thousandeyes/v7/regenerate-api-key/).

## Related Information

* [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control)
* [User API Tokens](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#user-api-tokens)
* [Built-In Roles and Permissions](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/built-in-roles-and-permissions)
* [Account Groups](https://docs.thousandeyes.com/product-documentation/user-management/authorization/account-groups)
* [Getting Started with the ThousandEyes API](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-the-thousandeyes-api)
* [ThousandEyes API documentation](https://developer.cisco.com/docs/thousandeyes/v7/)