All API requests must be authenticated by using an API key and a Connector ID. Unauthenticated requests return an HTTP 401 error.
Authentication is passed to the Cb Defense API via the
X-Auth-Token HTTP header. To generate the appropriate header, concatenate the API key with the connector ID with a forward slash in between. For example, if the API key is
ABCD and the connector ID is
1234, the corresponding
X-Auth-Token HTTP header will be:
A Cb Defense API Connector needs to be set up in Cb Defense Dashboard app under the Settings/Connector menu option. This allows a company administrator to define a connector and get access to the apiKey and connectorId that will be required to authenticate the API request. In addition, administrator can restrict use of this API key to a specific set of IP addresses for security reasons.
Currently there are three types of API keys available in the connectors page. Each key type provides different access levels to API routes:
APIkey type: provides access to all APIs except for the Notifications API and the Live Response API
SIEMkey type: provides access to the Notifications API
Live Responsekey type: provides access to all APIs available to (1) above plus the Live Response API
Attempting to access an API not allowed by a given key type will result in an HTTP 401 Unauthorized error.
Rate limiting is done on a per API key basis. Rate limiting interval is 5 minutes: 25 API calls every 5 minutes. When your request exceeds the rate limit for a given API key, the Cb Defense API will return an HTTP 429 “Too Many Requests” response code.
If you expect a lot of use, consider caching the results in your application. This should reduce the possibility of being rate limited.
We request that our customers honor the rate limits. If you or your application abuse the rate limits, the API key and or Organization will be blacklisted. Once an API key or Organization is blacklisted, you will be unable to get a response from Cb Defense API.