Get Started

This section describes the steps required to access the Tenable One Cloud Exposure API. You can find the full API schema in the GraphiQL explorer. To learn more about deprecated API fields, see Deprecation Policy.

The following steps are required to start interacting with the Cloud Exposure API:

  1. Create a service account and secret
  2. Find your organization's API endpoint
  3. Authenticate against the API endpoint
  4. Start querying the API

A detailed guide with examples is available below.

📘

Note

If you do not have experience working with GraphQL, consider consulting the GraphQL documentation.

Create a Service Account and Secret

Applications authenticate to the API with a secret that belongs to a service account. A service account replaces the API token used in earlier releases, holds up to two active secrets, and carries the roles that determine what the API calls can access.

📘

Note

Creating and managing service accounts requires the Settings permission. Cloud Exposure creates the service account in the scope currently selected in the scope selector at the top of the Console.

To create a service account and its first secret:

  1. In the left navigation bar, click Settings > Access Management > Service Accounts.

  2. Click Create.

  3. In the Name box, type a meaningful name for the service account.

  4. (Optional) In the Description box, type a description.

  5. (Optional) In the Role drop-down box, select a role. You can add a role later.

  6. Click Create.

    The Create New Secret window displays the first secret.

  7. Copy the secret to a secure location. The secret appears only once and cannot be viewed again.

  8. Click Close.

For the full set of service account tasks, including secret rotation, role assignment, and deletion, see Service Accounts in the Tenable Cloud Exposure User Guide.

📘

Note

Assign the service account a role with the permissions the API calls require. For more information about roles, see Roles and Permissions in the Tenable Cloud Exposure User Guide.

API Endpoints

The Cloud Exposure API is available at different endpoints, depending on the hosting region used during initial onboarding. The easiest way to determine which API endpoint your tenant belongs to is to view the URL in your browser while signed in to the Console.

Authentication

Authentication against the API endpoints uses the Bearer Authentication method. To make API calls, accompany every request header with an HTTP header named Authorization in the following format:

Authorization: Bearer <YOUR_SECRET>

No additional steps are required to authenticate.

Query the Graph

After the secret is available, you can start querying the graph. Access the API Explorer from your user profile in the top navigation bar of the Console.

For example, consider the following query for fetching the top 5 open critical findings:

curl --request POST \
  --url https://app.tenable.com/api/graph/ \
  --header "Authorization: Bearer ${API_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query {\n  Findings(\n    first: 5,\n    filter: {Statuses: Open, Severities: Critical}\n  ){\n    nodes {Id, CreationTime, __typename, Title, Severity, Labels}\n  }\n}"}'
📘

Note

Validate which API endpoint you are using.

In the above query, the following GraphQL operation runs:

query {
  Findings(
    first: 5
    filter: {
      Statuses: Open
      Severities: Critical
    })
  {
    nodes {Id, CreationTime, __typename, Title, Severity, Labels}
  }
}

Sample response

{
  "data": {
    "Findings": {
      "nodes": [
        {
          "Id": "ffeeddcc-1234-6789-bbaa-001122334455",
          "CreationTime": "2026-09-03T00:09:47.973Z",
          "Type": "AzureExcessivePermissionUser",
          "Title": "Overprivileged AAD user in subscription",
          "Severity": "Critical",
          "Labels": [
            "Admin"
          ]
        }
      ]
    }
  }
}

Query Blank Fields

You can query for blank values in all filterable fields.

Filter Blank Values

Use the null value to query for blank values in all filterable fields. For example, to query for all open findings that do not have a label:

query {
  AwsResources(
    filter: {
     Labels: [null]
    })
  {
    nodes {
      Name
      Labels
    }
  }
}

Sample response

{
  "data": {
    "AwsResources": {
      "nodes": [
        {
          "Name": "Demo1",
          "Labels": []
        },
        {
          "Name": "Demo2",
          "Labels": []
        }
      ]
    }
  }
}

Filter Blank Time Values

Use the IncludeNull parameter to query for blank values in time filters. For example, to query for AWS resources that were created in a specific time range or that do not have a specific creation time:

query {
 AwsResources(
    filter: {
      CreationTime:{
        startTime:"2026-09-11T07:49:05.000Z",
        endTime: "2026-10-11T07:49:05.000Z"
        IncludeNull:true
      }
    })
  {
    nodes {
      Name
      CreationTime,
  }
  }
}

Sample response

{
 "data": {
    "AwsResources": {
      "nodes": [
        {
          "Name": "Demo1",
          "CreationTime": null
        },
        {
          "Name": "Demo2",
          "CreationTime": "2026-09-11T07:49:05.000Z"
        }
      ]
    }
  }
}

You can query a specific range by filtering without the IncludeNull parameter, or by using IncludeNull:false.

query {
 AwsResources(
    filter: {
      CreationTime:{
        startTime:"2026-09-11T07:49:05.000Z",
        endTime: "2026-10-11T07:49:05.000Z"
      }
    })
  {
    nodes {
      Name
      CreationTime,
  }
  }
}

Sample response

{
  "data": {
    "AwsResources": {
      "nodes": [
        {
          "Name": "Demo2",
          "CreationTime": "2026-09-11T07:49:05.000Z"
        }
      ]
    }
  }
}

Navigate the Schema

The GraphiQL Explorer Docs is a built-in tool that helps you understand and interact with the Cloud Exposure API.

Video: Build a Sample Query

API Examples

See the following sections for a broad range of example queries:

Secret Management

A secret belongs to a service account, and the scope of the service account determines which accounts the secret can access. You create, generate, and delete secrets on the Service Accounts page, under Settings > Access Management.

Organization-Level Access

A service account scoped to the organization can access all accounts onboarded in the Cloud Exposure tenant. To grant organization-level access, assign the service account a role with an organization scope.

Account-Level Access

A service account scoped to a single account can access only that account. To grant account-level access, assign the service account a role scoped to the account.

For the full procedures to create a service account, assign roles and scopes, and generate secrets, see Service Accounts in the Tenable Cloud Exposure User Guide.

Delete a Secret

To delete a secret, open the actions menu for the service account on the Service Accounts page, click Manage Secrets, click the delete icon next to the secret, and then confirm the deletion in the Delete Secret window. Secret deletion is permanent and cannot be undone. A deleted secret cannot be recovered, and any code currently using it stops working immediately.

Resource Limitations

The Cloud Exposure GraphQL API has limitations in place to protect against excessive or abusive calls.

The current limitations are as follows:

  • API secrets are limited to 100 per tenant.
  • API rate limiting of 50 calls per second. This limit is per secret.

For information about creating and managing secrets, see Service Accounts in the Tenable Cloud Exposure User Guide.

Deprecation Policy

As part of the product lifecycle, API fields sometimes need to be renamed or removed. In such cases, Cloud Exposure marks them as deprecated to give you time to adapt to the changes. Deprecated fields are marked as deprecated, and an alternative field is suggested, as shown in the GraphiQL explorer.

Cloud Exposure marks a field as deprecated only if it has been queried consecutively. Once a field is deprecated, you are responsible for updating any code that uses the field to prevent workflow disruptions. Deprecated fields remain accessible for one month before removal. For a list of deprecated fields and their deprecation date, see Upcoming Changes and Compatibility Issues.


Did this page help you?