Introduction

Concepts required to access Carbon Black Cloud APIs:

1. Service Hostname
2. API Keys
3. RBAC
4. Organization Keys

Carbon Black Cloud Service Hostnames

There are two Carbon Black Cloud hostnames:

• https://defense-<environment>.conferdeploy.net/
• https://api-<environment>.conferdeploy.net/

In addition, we have multiple environments such as (not a complete list):

• prod02
• prod04
• prod05

Use your environment under the <environment> variable within the hostnames.

Please use the following table as a guide to map our services to hostnames.

API Keys

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:

• API Secret Key (previously API Key).
• API ID (previously Connector ID).

Authentication is passed to the API via the X-Auth-Token HTTP header.

• To generate the appropriate header, concatenate the API Secret Key with the API ID with a forward slash in between.
• For example, if the API Secret Key is ABCD and the API ID is 1234, the corresponding X-Auth-Token HTTP header will be:
  

X-Auth-Token: ABCD/1234

All API requests must be authenticated by using an API Secret Key and a API ID. Unauthenticated requests return an HTTP 401 error.

Note

Older versions of this document had “Connector” related terminology. This has now been updated to “API Key”.

• The Connectors page has been renamed to API Keys.
• Connector Type is now referred to as API Key Access Level.
• The API Key button that revealed the secret key is renamed to Credentials and shows both the ID and the Key.

How to obtain an API Secret Key and API ID

1. Log into your Carbon Black Cloud Organization.
2. Navigate to Settings > API Keys.
3. Click “Add API Key”.
4. Configure Name, Access Level, etc.
5. Obtain your API Secret Key and API ID pair.

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.

API Key Access Levels

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:

1. Custom Key Access Level: provides customizable authorization.
   • Custom API Keys are a result of our role based access control efforts (RBAC).
   • Allows customers to apply access controls and create least-privileged API keys.
   • Custom API Keys can be assigned User Roles or Access Levels.
   • Learn more about RBAC.
2. API Key Access Level: provides access to all APIs except for the Notifications API and the Live Response API.
3. SIEM Key Access Level: provides access to the Notifications API.
4. Live Response Key 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.

Role Based Access Control

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.

• With the rollout of User Roles and Access Levels, it is easy to customize your access to the Carbon Black Cloud APIs.
• Whenever possible, use API Keys with least privileged access.

Custom API Keys can be assigned User Roles or Access Levels.

User Roles

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.

• When selecting permissions for your user roles, reference the permission descriptions for additional detail, as needed.
• To add a new role click Add Role.
• Enter a unique name and description for the new role.
  • To add and remove permissions from an existing set of permissions, select a role from the copy permissions from dropdown, to use as a template.
  • To select permissions without a template, set copy permissions from to None.
• Select or unselect the desired permissions for the role, then click Save.

Access Levels

• Access Levels allow Carbon Black Cloud organization administrators to define granular authorization permissions to API Keys.
• An access level is a combination of multiple individual permissions.
• Each individual permission has Create, Read, Update, Delete, and Execute operations.
  • Each individual permission has one or more of the C, R, U, D, E operations available to be enabled or disabled.
• As we continue to update and improve our APIs, additional routes will be made available in future releases to allow full customization of permissions and access levels.

Permissions

An access level is made up of multiple individual permissions.

• Permissions are uniquely identified by their .notation name.
• Each permission has one or more Create, Read, Update, Delete, and Execute operations available to be selected.

Access Levels in the Console

View access levels in the Carbon Black Cloud Console under Settings > API Keys > Access Levels (Tab). To create access levels, follow these steps:

• Navigate to Settings > API Keys > Access Levels.
• Click Add Access Levels.
• Enter a unique name and description for the new access level.

Example

1. Create a new Access Level and name it Help Desk Scripts.
2. Add permissions (using notation names) - livequery.manage, threathunter.feeds.
   1. For livequery.manage, assign create and read operation(s).
   2. For threathunter.feeds, assign create and read operation(s).
3. Save the access level.
4. Create a new API Key and assign the custom access level as developer.example.

You have now created an API Key which has the ability to:

• Create LiveQuery Runs
• Read LiveQuery Run Results
• Create ThreatHunter Feeds
• Read ThreatHunter Feeds

Carbon Black Cloud Service to API Access Level Correlation

Organization Keys

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.