Tenable.sc API Key Usage
Overview
In Tenable.sc 5.13.0 users will be able to authenticate to the system by using an API Key. This API Key is similar to Tenable.io’s API Key where it is divided into two parts (an “Access Key” and a “Secret Key”) and allows access to the API Endpoints without requiring an authentication token to be generated previously and used in the header. Furthermore, a Tenable.sc system administrator will be able to toggle this functionality on and off system-wide.
Nomenclature
- User
An administrator or organizational level account on a Tenable.sc system.
- Access Key
One half of an API Key that is used for identifying which user is accessing the system. This information is visible on a users’ information as well as in the system logs.
- Secret Key
One half of an API Key that is used in conjunction with the Access Key to allow authenticate to the system. This information is not visible after generating an API Key.
- API Key
The combined Access Key and Secret Key that uniquely identifies and authenticates a user of the Tenable.sc system. This documentation uses “API Key” in the singular to refer to a unique combination of an Access Key and Secret Key.
Usage
An API Key is another method of authentication for a user much like a password. An API Key is assigned to a single user and allows that user to authenticate to any Tenable.sc endpoint without having to first authenticate to the system and receive a token. The API Key can be generated/deleted by the user who wishes to authenticate to the system in this manner as well as any user who has permission to manage that user’s password. Furthermore, a System Administrator level account can generate/delete an API Key of any user in the system. When a user attempts to authenticate to Tenable.sc with an API Key the Access Key used is logged for identification purposes in a similar manner to logging that utilizes the authentication token.
When calling any Tenable.sc endpoint an additional header of “x-apikey” can now be passed in. The value of this header should be of the form “accesskey=<accessKey>;secretkey=<secretKey>” for it to be correctly parsed. More specifically the header value is converted to lowercase and then checked against the regex “accesskey\s*=\s*(\w{32})\s*;\s*secretkey\s*=\s*(\w{32}).*”. If the value does not pass this regex the Tenable.sc system will not recognize your API Key correctly.
A System Administrator can enable or disable the functionality of this feature across the entire system by going to the Security section of the Configurations page and then toggling on or off the “Allow API Keys” entry. It is important to note that the “Allow API Keys” toggle does not disable/enable the API Key Endpoints listed in the Tenable.sc API Documentation. It only disables/enables a user being able to authenticate to the system with an API Key.
Error States
The following new usages of the API are now considered an error state and will return an appropriate error message:
- Passing in an Authentication token (via the “x-securitycenter” header) and an API Key in the same request is considered an invalid request and will return HTTP 400 (Bad Request).
- Passing an API Key when the API Key functionality is disabled is considered an invalid request and will return HTTP 400.
- Any errors that result from the API Key recognition process attempting to access the database is considered an invalid request and will return HTTP 400.
- Passing an invalid API Key is considered an invalid request and will return HTTP 400. An invalid API Key is an API Key that meets any of the following criteria:
The Access Key and Secret Key combined do not have a length of 64 characters.
The Access Key does not exist in the database.
The user associated with the API Key is locked.
The current system time is past the expiration time of the API Key (By default API Keys do not have an expiration time set).
The Access Key and Secret Key combination is not correct for the specified Access Key.
These error messages are logged like any other usage of the API that generates an error message.
Example
curl -X GET -k --header “x-apikey:accesskey=4def6bc216f14c1ab86dfba8738ff4a5;secretkey=a47d1d3a071443449a75821129526b96” https://Tenable.sc/rest/currentUser
