Get Started

Tenable Identity Exposure provides a REST API on each instance. Requests authenticate with the API key of a Tenable Identity Exposure user, and each request is subject to that user's role permissions and to the instance license.

To start using the Tenable Identity Exposure API:

1. Find your instance URL.
2. Get an API key.
3. Authenticate your requests.

📘

Note

This documentation describes Tenable Identity Exposure SaaS. The API reference uses API names, such as infrastructure and directory, that differ from the interface terms, such as forest and domain. For the full list, see Terminology.

Find Your Instance URL

Each instance has its own base URL, https://{customer}.tenable.ad, where {customer} is the name of your instance. Every endpoint path begins with /api. For example, the current user's details are at https://{customer}.tenable.ad/api/users/whoami.

Get an API Key

Each user has one API key. The key carries the permissions of the user's roles, so a request made with it can do only what that user can do.

To view or refresh your API key in the interface:

1. In Tenable Identity Exposure, click your user profile icon and select Preferences.

   The Preferences pane opens.

2. From the menu, select API key.

   Tenable Identity Exposure shows your current API key.

3. To generate a new key, click Refresh API key, then click Confirm.

For more information, see Tenable One Identity Exposure Public API in the Tenable One Identity Exposure SaaS User Guide.

To manage the key through the API, use the Get API key endpoint, which returns the current user's key, and the Create API key endpoint, which generates a new one.

Keep the following in mind:

• Viewing a key requires the read:api-key permission, and generating one requires edit:api-key. The User role as Tenable provides it holds neither, so a user who holds only that role can neither view nor generate a key until an administrator grants the permissions. For more information, see Identity Exposure Roles.
• Generating a new key deactivates the previous one immediately. Update every integration that uses the old key.

🛑

Caution

If a change to a role leaves a user without edit:api-key, Tenable revokes that user's API key. Restoring the permission does not reactivate the key: the user must generate a new one.

Authenticate Your Requests

Send the API key in the x-api-key header of every request.

📘

Note

Tenable Identity Exposure uses the x-api-key header, not the X-ApiKeys header used by Tenable Vulnerability Management and the Tenable Platform APIs, and the key is a single value rather than an access key and secret key pair.

For example, to confirm that your API key works, you could use the following cURL request, which returns the details of the user the key belongs to:

curl --request GET \
  --url https://your-instance.tenable.ad/api/users/whoami \
  --header 'accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

Replace your-instance with the name of your instance. If the key is invalid, the request returns a 401 response.

Sign In with a Token

As an alternative to an API key, a user who signs in with an email address and password can request a session token. The Log in endpoint returns the token in the authToken property. Send it in the x-auth-token header in place of x-api-key:

curl --request GET \
  --url https://your-instance.tenable.ad/api/users/whoami \
  --header 'accept: application/json' \
  --header 'x-auth-token: YOUR_AUTH_TOKEN'

The Log out endpoint ends the session, after which the token is no longer valid. A role change that removes edit:api-key does not affect a session token.

Permissions and Licenses

Each endpoint's description states what it requires:

• License types. Most endpoints require the instance license to include Indicators of Exposure, Indicators of Attack, or either one. For the codes the descriptions use, see License Types.
• Permissions. The permission callout at the end of each description names the permissions the user's roles must grant. A request without them returns a 403 response with the code RBAC_RESTRICTION, and the error title names the missing permission. For the permission model, see Identity Exposure Permissions.