API Gateway overview

Tanium™ API Gateway provides a single and stable API integration point for various Tanium solutions. It is designed for Tanium partners and customers interested in building integrated solutions with the Tanium™ Core Platform.

Query explorer

API Gateway includes an interactive query explorer that you can use to write and run queries and mutations in the Tanium Console. Use the query explorer to try new queries and discover what data is available.

You can find the query explorer on the API Gateway Overview page:

Query explorer

If the query explorer does not appear on the API Gateway Overview page, click Customize Page and make sure the Query Explorer option is selected.

 

Query variables

If a query or mutation uses variables, expand the QUERY VARIABLES pane and include the variables in the pane that expands.

 

 

Schema reference

API Gateway contains a schema reference that documents all queries, mutations, and objects that are available in API Gateway. The schema reference is generated directly from the schema; refer to the schema reference in API Gateway for the most up-to-date documentation.

To view the schema reference in the query explorer, click Docs to expand the Documentation Explorer pane of the query explorer.

 

 

The query explorer uses the GraphiQL interactive browser to send GraphQL queries and mutations to the Tanium ServerTanium as a Service. For more information about the options that are available in GraphiQL, see https://graphql.org/learn/.

Authentication

Requests that are sent from the query explorer in the Tanium Console are authenticated and authorized with the session ID of the user who is signed in. The Tanium ServerTanium as a Service uses the role-based access control (RBAC) permissions of the user account to determine which content you can query and mutate.

Requests that are sent from outside the Tanium Console are authenticated and authorized with either session IDs or API tokens. You must include an API token or session ID in the authorization header of all requests that are sent to API Gateway. API Gateway uses the RBAC permissions of the requesting user to determine content access for all queries and mutations. For an example cURL query that shows the authorization header, see Example cURL syntax.

Use API tokens to send requests through API Gateway instead of session IDs. While session IDs time out after five minutes of inactivity, you can set a longer timeout for API tokens. You can create API tokens in the Tanium Console or through the Tanium Core Platform REST API. For more information, see Tanium Console User Guide: Managing API tokens.

When requests are sent outside the Tanium Console, make sure to use the correct URL to send requests. See Root endpoint and Example cURL syntax for examples.

Rate limits

API Gateway has no specific rate limits.

Tanium as a Service imposes rate limits on incoming requests. If you exceed the rate limits, any mutations and queries return an HTTP 429 error. For information on rate limits in Tanium as a Service, see Getting started with TaaS.

Root endpoint

To send queries and mutations outside the Tanium Console, use the following address:

https://<server>/plugin/products/gateway/graphql

https://<customerName>-api.cloud.tanium.com/plugin/products/gateway/graphql

Example cURL syntax

curl --request POST \
   --url https://localhost/plugin/products/gateway/graphql \
   --header 'Content-Type: application/json' \
   --header 'session: token-356d5f5bbb3671f28e24f65be3bdd54d9d81001ca823efaabc5fbff251' \
   --data '{"query":"{\n  now\n}\n"}'
curl --request POST \
   --url https://acme-api.cloud.tanium.com/plugin/products/gateway/graphql \
   --header 'Content-Type: application/json' \
   --header 'session: token-356d5f5bbb3671f28e24f65be3bdd54d9d81001ca823efaabc5fbff251' \
   --data '{"query":"{\n  now\n}\n"}'

Pagination

Queries that return many results are paginated to reduce resource utilization. API Gateway uses the standard Relay GraphQL pagination specification to provide users the option to explicitly control pagination.

Paginated queries return a connection type that is prefixed with the name of the data type, such as EndpointConnection. Queries accept standard arguments to control the pagination.

Example of a paginated query:

Copy
{
  endpoints {
    edges {
      node {
        id
        serialNumber
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Cursors

Use cursors to control relay pagination. Cursors are opaque strings that point to records within queried collections, and can be used to request the records after the cursor. All collections support forward traversal, and some also support backward traversal.

Cursors are valid only for the query for which they were returned. Cursors are generally valid for five minutes after their most recent use. Any queries that deviate from this policy are documented in the query field.

Connection results are stable and consistent when traversed with cursors unless documented in the query field.

Connection and edges

The connection includes an edge field that returns a list of typed edges, such as EndpointEdge. Each edge contains at least two fields:

  • A node field with the actual data type, such as Endpoint
  • A cursor field with a cursor for the record

The connection type also includes a pageInfo field that contains at least two fields:

  • hasNextPage indicates if there are more records
  • endCursor is the cursor of the last record in the returned page, if any

Some connection types feature other metadata, such as totalRecords.

Arguments

Paginated queries support at least two arguments: first indicates the number of records to return, and after is the value of the record cursor that precedes the records in the requested page. When fully paginated, this value is the same as the endCursor value from the previous page. Both arguments have sensible defaults.

Paginated queries that support backward traversal allow two corresponding arguments: last and before.

A single query supports either forward or backward traversal, but not both. The serverTanium as a Service returns an error response for queries with arguments for both forward and backward traversals.

When a paginated request extends beyond the collection, the query returns only the available results.

Example of a request for a page of data within a collection:

Copy
{
  endpoints(after: "the-cursor-value", first: 10) {
    edges {
      node {
        id
        serialNumber
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filters

Most queries that return multiple results provide support to filter the results. Such queries provide a filter argument.

Simple filters

Simple filters are single filters that constrain the values of fields that participate in the query. You can specify simple filters in the path property with a period to separate levels in the graph starting at the record type. For example:

Copy
{
  endpoints(filter: {path: "primaryUser.email", value: "[email protected]"}) {
    edges {
      node {
        id
        primaryUser {
          email
        }
      }
    }
  }
}

The query does not need to return the filtered path. Not all field paths are filterable. Refer to the schema to see which paths cannot be filtered.

Simple filters must also contain a string value property.

You can specify an operator in the op property, which is an enumerated type and defaults to the equality operator. For example:

Copy
{
  endpoints(filter: {path: "processor.logicalProcessors", value: "4", op: GTE}) {
    edges {
      node {
        id
      }
    }
  }
}

Not all operators are valid for all fields.

Compound filters

Compound filters contain multiple simple or compound filters that appear in the filters property. By default, all child filters must pass for a record to be included. If the or argument is given with a true value, then a record is included if any child filter matches.

Example of a simple compound filter:

Copy
{
  endpoints(filter: {filters: [{path: "serialNumber" value: "x"}, {path: "name", value: "y"}]}) {
    edges {
      node {
        id
      }
    }
  }
}

Negated filters

You can negate both simple and compound filters with a negated property of true. For example, the following query returns endpoints whose serial number does not contain the letter x:

Copy
{
  endpoints(filter: {path: "serialNumber", value: "x", negated: true}) {
    edges {
      node {
        id
      }
    }
  }
}

Field filters

Filters apply to the entire record. Some records contain fields that are collections; you can also filter these fields. When you filter a field, the filter applies to both the child collection and to the records. For example, if you search for endpoints with an installed application named Tanium Client with a filter on the field, API Gateway returns only those endpoints with such an application, as well as only the matching application:

Copy
{
  endpoints {
    edges {
      node {
        installedApplications(filter: {path: "name", value: "Tanium Client"}) {
          name
          version
        }
      }
    }
  }
}

Field filters can be simple or compound. Compound filters are limited to one level of children that must use the equality operator, and require all child filters. For example:

Copy
{
  endpoints {
    edges {
      node {
        installedApplications(
          filter: {
            filters: [
              {path: "name", value: "Tanium Client"},
              {path: "version": value: "7.5.0.0"}
            ]
          }
        ) {
          name
          version
        }
      }
    }
  }
}

Integration with other Tanium products

The following solutions are supported by API Gateway:

  • Tanium Core Platform
    • Actions
    • Tanium™ Data Service
    • Tanium™ Direct Connect
    • Packages
  • Tanium™ Blob
  • Tanium™ Deploy
  • Tanium™ Performance