Concepts required to access Carbon Black Cloud APIs:
There are two Carbon Black Cloud hostnames:
In addition, we have multiple environments such as (not a complete list):
Use your environment under the
<environment> variable within the hostnames.
Please use the following table as a guide to map our services to hostnames.
Carbon Black Cloud APIs and Services are authenticated via API Keys. Users can view API Key settings within the Carbon Black Cloud Console under Settings > API Keys.
API keys include two parts:
Authentication is passed to the API via the
X-Auth-Token HTTP header.
ABCDand the API ID is
1234, the corresponding
X-Auth-TokenHTTP header will be:
All API requests must be authenticated by using an API Secret Key and a API ID. Unauthenticated requests return an HTTP 401 error.
Older versions of this document had “Connector” related terminology. This has now been updated to “API Key”.
This allows a organization administrator to define a API Key and get access to the API Secret Key and API ID that will be required to authenticate the API request. In addition, administrators can restrict use of this API key to a specific set of IP addresses for security reasons.
Currently there are four major access levels for API Keys available in the API Keys page. Each access level provides different access levels to API routes:
CustomKey Access Level: provides customizable authorization.
APIKey Access Level: provides access to all APIs except for the Notifications API and the Live Response API.
SIEMKey Access Level: provides access to the Notifications API.
Live ResponseKey Access Level: provides access to all APIs available to (1) above plus the Live Response API.
Attempting to access an API not allowed by a given API Key Access Level will result in an HTTP 401 Unauthorized error.
Through our investment in APIs and integrations we aim to provide customers and partners with the core capabilities of the Carbon Black Cloud, securely and flexibly integrated within their security stack. To do so, we’re launching a new workflow featuring Custom Access Levels for API Keys, which allows customers to apply access controls and create least-privileged API keys.
This new workflow will help us deliver more value through API Keys with a new set of API points to manage alerts and endpoints.
Custom API Keys can be assigned User Roles or Access Levels.
User Roles are accessible in the Carbon Black Cloud Console under Settings > Roles.
Create custom roles with specific permission levels. Roles are available to assign to your console users from the Users page.
An access level is made up of multiple individual permissions.
View access levels in the Carbon Black Cloud Console under Settings > API Keys > Access Levels (Tab). To create access levels, follow these steps:
Help Desk Scripts.
livequery.manage, assign create and read operation(s).
threathunter.feeds, assign create and read operation(s).
You have now created an API Key which has the ability to:
|API/Service Category||API Key Access Level(s) Permitted|
In addition to API Keys, many Carbon Black Cloud APIs or Services require an
org_key in the API request path. This is to support customers that manage multiple orgs.
You can find your
org_key in the Carbon Black Cloud Console under Settings > API Keys.