DocumentationAPI ExplorerRecipesCommunityChangelogRSSSubscribe
Changelog
Back to All
added

Tenable.io API User-Agent Header

about 4 years ago by Lance Duvall

Tenable recommends the use of a standard User-Agent string in request headers when building integrations with the Tenable.io API. A standard User-Agent string helps Tenable to identify your integrations and API calls, and it assists in debugging and troubleshooting if you have issues with the API, rate limits, or concurrency limits.

Tenable recommends the following standardized User-Agent string format:

Integration/1.0 (VENDOR; PRODUCT; Build/VERSION)

The attributes in the User-Agent string are defined as follows:

  • VENDOR—The name of your company or business entity.
  • PRODUCT—The name of your product or integration. This attribute allows the ability to distinguish between multiple integrations if you have multiple integrations with the Tenable.io API.
  • VERSION—The version identifier. This attribute allows the ability to track the various versions of your integrations being used.

The User-Agent string format defined above helps Tenable to identify who the integration belongs to, what product the integration is working on behalf of, and what version of the integration is being used. Additionally, the User-Agent string is extensible and allows for more attributes to be added after the Build attribute should you desire.

For example, to use the User-Agent string Integration/1.0 (ACME Industries; FancyIntegration; Build/1.0) in a cURL request to return a list of list users, you would use the following:

curl --request GET \
  --url https://cloud.tenable.com/users \
  --header 'accept: application/json' \
  --header 'x-apikeys: accessKey=ACCESS_KEY;secretKey=SECRET_KEY' \
  --header 'User-Agent: Integration/1.0 (ACME Industries; Fancyintegration; Build/1.0)'

It's also easy to use the User-Agent string in pyTenable by passing the right parameters to the constructor:

```python
>>> from tenable.io import TenableIO
>>> tio = TenableIO(vendor='ACME Industries', product='FancyIntegration', build='1.0')
>>> tio._session.headers['User-Agent']
'Integration/1.0 (SMC Industries; Fancypants; Build/1.0) pyTenable/0.3.28 (pyTenable/0.3.28; Python/3.7.3; Darwin/x86_64)'
```

Note that in the last line, the User-Agent string being passed has the Integration format as well as the information for pyTenable.

The information contained in this changelog entry is also documented on the User-Agent Header page in the API Basics section.