Carbon Black Cloud API Access
Introduction
This guide covers the steps required for accessing Carbon Black Cloud APIs:
- Authenticate your request
- Construct your Request
- Structure of Base URLs
- Make the Request
- Troubleshooting
Make a Call
As either a quick start or to know where we are going, this a sample request to get all devices with a specific id. Follow the information on this page for info on how to create them.
X-Auth-Token
The X-Auth-Token authentication method uses the API Id and Secret directly in the call to the Carbon Black Cloud APIs.
This is a valid cURL request - some values need to be replaced with yours.
curl https://defense.conferdeploy.net/appservices/v6/orgs/ABCD1234/devices/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \
-d '{"criteria": {"id": [ "1234567" ]}}'
This is the same request with the variables named. Follow the information on this page for info on how to create them.
$ curl {cbc-hostname}/{API Service Category}/{API path} \
-X POST \
-H 'X-Auth-Token: {API Secret}/{API ID}' \
-H 'Content-Type: application/json' \
-d '{{request body}}'
For a tutorial on how to make API calls and some commonly used tools, see the series of videos for Getting Started with APIs on Tech Zone.
Authenticate your Request
Carbon Black Cloud APIs and Services are authenticated via API Keys. In order to access the data in Carbon Black Cloud via API, you must set up keys with the correct permissions for the calls you want to make. All APIs use an Access Level type of Custom
.
For more information about Role-Based Access, see the RBAC Guide.
Carbon Black Cloud Manages identities and roles
1. 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 Data Forwarding category.*

For more information about Role-Based Access, see the RBAC Guide.
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
• Access Level types of `API`, `LIVE_RESPONSE` and `SIEM` are deprecated. See the Migration Guides for details of how to move to new APIs.

5. Hit save, and you will be provided with your API Key Credentials:
• API Secret Key (store the API Secret Key somewhere securely, because it cannot be retrieved after initial creation)
• API ID
6. If your API Key already exists, you can view your credentials by opening the Actions dropdown and selecting API Credentials. This will reveal your API ID, but not your API Secret Key. However if the API Secret Key is not stored anywhere, you can reset it.
• If your system becomes compromised, you can generate a new secret key here (this is like changing the password for your application or script).

Construct your Request
You will need to construct your base URL in order to run the API calls.
Build the Base URLs
The base URL is comprised of the following:
- Hostname + Environment (based on your organization’s product instance)
- API Service Category (based on which Carbon Black Cloud product the API is for)
- API path (based on the API version you choose)
- Org key (found in your product console under Settings > API Access > API Keys)
These components are put together in the following structure:
Hostname / API Service Category / API Path / Org Key
The URL Parts
Hostname
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.
Environment | hostname |
---|---|
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 |
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, Devices, Live Response and Reputation Override APIs v6/data_forwarder/
for the Data Forwarder Configuration APIs (previously Event Forwarder)/investigate/
for the Platform Search APIs (Processes or Enriched Events)/jobs/
for the Jobs Service APIs/policyservice/
for policy management APIs/sus/
for the Sensor Update Service APIs/vulnerability/assessment/api/
for the Vulnerability Assessment APIs
- Enterprise EDR APIs use one of the following API Service Categories:
/threathunter/
for the Feed Search, Feed Manager and Watchlist 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:
/device_control/
for the Device Control APIs/integrationServices/
for the Integration Service APIs for Audit Logs and Notification APIs/investigate/
for the Enriched Events Search APIsrecommendation-service
for the Recommendation API
- Workload APIs use one of the following API Service Categories:
/applianceservice/
for the Appliance Service APIs/lcm/view/
for the VM Workloads Search APIs/lcm/
for the Sensor Lifecycle Management APIs/public-cloud/account-management/
for Public Cloud Account Management
API Path
The API Path is specific to the API call you’re using. Usually it is the API version, e.g. v1.
Org Key
Most 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 > General, and if Carbon Black Cloud manages your identities it is also available on Settings > API Access. - When inserting your Org Key, do not include any < > or { } brackets around the value.
Structure of Base URLs
Get your {hostname} from the section above.
Follow the API Name for details on the request and response structure for each API call.
As of July 2023, all APIs use Custom API Keys. See the Migration Guides for details of how to move to new APIs.
Product & API Name | Service Category | Base URL Structure |
---|---|---|
Platform (Any Carbon Black Cloud Product) | ||
Access Profiles and Grants | /access/ |
{hostname}/access/v2/orgs/{org_key}/ |
Alerts | /api/alerts/ |
{hostname}/api/alerts/v7/orgs/{org_key}/alerts |
Data Forwarder Configuration | /data_forwarder/ |
{hostname}/data_forwarder/v2/orgs/{org_key}/configs |
Devices | /appservices/ |
{hostname}/appservices/v6/orgs/{org_key}/devices |
Jobs Service | /jobs/ |
{hostname}/jobs/v1/orgs/{org_key} |
Live Response v6 | /appservices/ |
{hostname}/appservices/v6/orgs/{org_key}/liveresponse |
Policy | /policyservice/ |
{hostname}/policyservice/v1/orgs/{org_key}/policies |
Process Search | /investigate/ |
{hostname}/investigate/{v1 or v2}/orgs/{org_key} |
Reputation Override v6 | /appservices/ |
{hostname}/appservices/v6/orgs/{org_key}/reputations/overrides |
Sensor Update Service | /sus/ |
{hostname}/sus/v3/orgs/{org_key} |
User Management | /appservices/ |
{hostname}/appservices/v6/orgs/{org_key}/users |
Vulnerability Assessment | /vulnerability/assessment/api/ |
{hostname}/vulnerability/assessment/api/v1/orgs/{org_key} |
Endpoint Standard | ||
Audit Logs | /integrationServices/ |
{hostname}/integrationServices/v3/auditlogs |
Device Control | /device_control/ |
{hostname}/device_control/v3/orgs/{org_key} |
Recommendation | /recommendation-service/ |
{hostname}/recommendation-service/v1/orgs/{org_key} |
Enterprise EDR | ||
Feed Manager | /threathunter/feedmgr |
{hostname}/threathunter/feedmgr/v2/orgs/{org_key}/feeds |
Feed Search | /threathunter/feedsearch |
{hostname}/threathunter/feedsearch/v1/orgs/{org_key}/search |
Unified Binary Store | /ubs/ |
{hostname}/ubs/v1/orgs/{org_key} |
Watchlist | /threathunter/watchlistmgr/ |
{hostname}/threathunter/watchlistmgr/v3/orgs/{org_key}/watchlists |
Audit and Remediation | ||
Differential Analysis | /livequery/ |
{hostname}/livequery/v1/orgs/{org_key}/differential |
Live Query | /livequery/ |
{hostname}/livequery/v1/orgs/{org_key} |
Workload | ||
Appliance Service | /applianceservice/ |
{hostname}/applianceservice/v1/orgs/{org_key} |
Sensor Lifecycle Management | /lcm/ |
{hostname}/lcm/v1/orgs/{org_key} |
NSX Remediation | /applianceservice/ |
{hostname}/applianceservice/v1/orgs/{org_key} |
Public Cloud Account Management | /public-cloud/account-management/ |
{hostname}/public-cloud/account-management/v1/orgs/{org_key} |
VM Workloads Search v2 | /lcm/view/ |
{hostname}/lcm/view/v2/orgs/{org_key} |
Make the Request
Now you have all the information needed to populate the template curl request from the beginning and make your own request.
$ curl {cbc-hostname}/{API Service Category}/{API path} \
-X POST \
-H 'X-Auth-Token: {API Secret}/{API ID}' \
-H 'Content-Type: application/json' \
-d '{{request body}}'
Troubleshooting
Troubleshooting Access Levels
Problem: Unable to edit Access Level
Reason: The access level likely contains permissions that you as a user do not have.
There are two reasons this can happen.
The Access Level is type custom and contains permissions you as a user do not have
- Check that you can create a new Access Level and assign it to a new API Key; this verifies you have the necessary Manage API Key permissions
- Have someone compare the permissions your user role has to the permissions the troublesome API Access Level has
Troubleshooting REST API Errors
Suggested fix: Verify that your request adheres to API documentation.
Suggested fix: Check that your X-Auth-Token matches the format secret_key/api_id and that the values are correct.
Suggested fix: If it has a Custom access level, check it has been assigned the correct RBAC permissions. If it is an API, SIEM or LIVE_RESPONSE type Access Level, verify it is the right Access Level type for the API in use.
Suggested fix: Verify that your request contains objects that haven’t been deleted. Verify that the`org_key`in the path is correct.
Suggested fix:
• Verifying the correct verb and route by comparing with the API documentation on the Developer Network.
• Verifying the correct hostname by comparing it with the Authentication page on the Developer Network or the CBC URL.
Suggested fix: Change any spaces in the name to underscores. Look through your list of API Keys and see if there is an existing key with the same name.
Suggested fix: It is likely this API was deactivated. Review the documentation to find the replacement and migration information.
Suggested fix: This can happen if too many file downloads are happening at the same time. You can try later.
Suggested fix: Something went wrong on the back end. Try the request again and if it happens consistently open a support case.
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
Last modified on September 21, 2023