Introduction

This guide covers the steps required for accessing Carbon Black Cloud APIs:

1. Authenticating your request
   • Creating a Custom Access Level
   • Creating an API Key
2. Constructing your Request
   • Building a Base URL (Prod05 Example)
   • Explaining the URL Parts
3. Index of Base URLs
4. Troubleshooting

Authenticating your Request

Carbon Black Cloud APIs and Services are authenticated via API Keys. This means that in order to access the data in Carbon Black Cloud via API, you must set up Access Levels and API Keys in the Carbon Black Cloud Console.

The first step of Authentication is determining the appropriate access level for the API. The table below provides the Access Levels permitted for each Service Category of APIs. The service category maps to the Carbon Black Cloud product you use, and some products have multiple service categories. If your API is “Custom”, you will need to create a Custom Access Level in the Carbon Black Cloud console before you create an API Key.

Creating a Custom Access Level

1. If your service category requires Custom Access Level, go to your Carbon Black Cloud console, and open the “Add Access Level” panel from Settings > API Access > Access Levels tab.
2. Give the access level a unique name (you will need this for creating your API Key) and give it a description.
3. From the table below, scroll down until you see your API Service Category. Some Service Categories have multiple permissions that can be configured. The API documentation will indicate which permissions are required for each call.

This example shows the permissions “Create”, “Read”, “Update”, and “Delete” are granted for the Settings permissions in the Event Forwarding category.

For more information about Role-Based Access, see the RBAC Guide.

Creating an API Key

This is like adding a user to a system and setting their access level, except you are granting access to your application or script instead of a user.

1. To create an API Key, go to Settings > API Access > API Keys tab in the Carbon Black Cloud console.
2. Select “Add API Key” from the far right.
3. Give the API Key a unique name, and select the appropriate access level provided in the table above. If you select “Custom”, you will need to choose the Access Level you created in the prior section.
   • Choose a name to clearly distinguish the API from your organization’s other API keys.
     Example: Event_Forwarder_Test_Key
   • You can also add Authorized IP addresses and a description to differentiate among your APIs. Administrators can restrict use of an API key to a specific set of IP addresses for security reasons.

4. Hit save, and you will be provided with your API Key Credentials:
   • API Secret Key
   • API ID
5. If your API Key already exists, you can view your credentials opening the Actions dropdown and selecting API Credentials. This will reveal your API Secret Key and API ID.
   • If your system becomes compromised, you can generate a new secret key here (this is like changing the password for your application or script).

6. Next, pass your credentials into 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: X-Auth-Token: [API Secret Key]/[API ID]

Example: If Adam from Company Q has the API Secret Key ABCDEFGHIJKLMNOPQRSTUVWX and the API ID of 12345678, his corresponding X-Auth-Token HTTP header is:

X-Auth-Token: ABCDEFGHIJKLMNOPQRSTUVWX/12345678

Constructing your Request

You will need to construct your base URL in order to run the API calls.

First you need to determine which environment, or product URL you use. You can find this by looking at the web address of your Carbon Black Cloud console. Select your URL to view a table with the base URL for each product and API.

• EAP01 - https://defense-eap01.conferdeploy.net
• Prod 01 - https://dashboard.confer.net/
• Prod 02 - https://defense.conferdeploy.net/
• Prod 05 - https://defense-prod05.conferdeploy.net/
• Prod 06 - https://defense-eu.conferdeploy.net/
• Prod NRT - https://defense-prodnrt.conferdeploy.net/
• Prod Syd - https://defense-prodsyd.conferdeploy.net/

Read on for instructions on how to construct a base URL for the prod05 environment.

Building your Base URLs

The base URL is comprised of the following:

• Hostname + Environment (based on your organization’s product instance)
• Service Category (based on which Carbon Black Cloud product the API is for)
• API route (based on the API version you choose)
• Org key (found in your product console under Settings > API Access > API Keys)

If your organization uses the prod05 environment (i.e., your product URL is https://defense-prod05.conferdeploy.net/), you may use the following format to construct your base URL:

Hostname / API Service Category / API Path / Org Key

Explaining the URL Parts

Hostname

There is currently one hostname used for Carbon Black Cloud products:

• For all APIs (Platform, Endpoint Standard, Enterprise EDR, Audit and Remediation), use the dashboard URL for the hostname: https://defense-prod05.conferdeploy.net/

API Service Category

The API Service Category corresponds to the Carbon Black Cloud product and API you use

• Platform APIs use one of the following API Service Categories:
  • /appservices/ for Alerts and Devices APIs
  • /event-forwarder-config/ for the Event Forwarder Configuration APIs
  • /investigate/ for the Platform Search APIs (Processes or Enriched Events)
  • /sus/ for the Sensor Update Service APIs
  • /jobs/ for the Jobs Service APIs
• Enterprise EDR APIs use one of the following API Service Categories:
  • /threathunter/ for the Feed Search and Feed Manager APIs
  • /investigate/ for the Process Search APIs
  • /ubs/ for the Unified Binary Store REST API
• Audit and Remediation APIs use /livequery/
• Endpoint Standard APIs use one of the following API Service Categories:
  • /integrationServices/ for the Integration Service APIs
  • /device_control/ for the Device Control APIs
• Workload APIs use one of the following API Service Categories:
  • /applianceservice/ for the Appliance Service APIs
  • /vulnerability/assessment/api/ for the Vulnerability Assessment APIs
  • /lcm/view/ for the VM Workloads Search APIs
  • /lcm/ for the Sensor Lifecycle Management APIs

Org Key

Many Carbon Black Cloud APIs or Services require an org_key in the API request path to support customers who manage multiple organizations.

• You can find your org_key in the Carbon Black Cloud Console under Settings > API Access.
• When inserting your Org Key, do not include any < > or { } brackets around the value.

Index of Base URLs

Base URLs for EAP01

Base URLs for Prod 01

Base URLs for Prod 02

Base URLs for Prod 05

Base URLs for Prod 06

Base URLs for Prod NRT

Base URLs for Prod Syd

Troubleshooting

Troubleshooting REST API Errors

Other Troubleshooting Tips

• When passing your auth token in the header, make sure the API Secret Key is first and the API ID is second.
• Make sure you are using your own API Secret key from the product console and not ABCDEFGHIJKLMNOPQRSTUVWX.
• When inserting your Org Key, do not include any < > or { } brackets between the backslashes.
• An HTTP 401 Unauthorized error can occur if you attempt to access an API that is not allowed by a given API Key Access Level.
• If you have issues, try testing in Postman so you can evaluate your request in a raw format before scripting.

Related Resources & Guides

• RBAC Guide