Carbon Black Cloud API Access

Introduction

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

Determine whether you are using Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization
Authenticate your request
Construct your Request
- Build a Base URL
- The URL Parts
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}}'

OAuth App with Bearer

First use the OAuth App Id and Secret (obfuscated with base64 encoding) to get an Access Token.

curl --request POST '{csp-hostname}/csp/gateway/am/api/auth/token' \
--header 'Authorization: Basic {base64(App ID:App Secret)}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Then use the Access Token to call Carbon Black Cloud APIs.

curl --request GET '{cbc-hosthame}/appservices/v6/orgs/{org_key}/devices/{device_id}' \
--header 'Authorization: Bearer {csp-generated-access-token}' \
--header 'Content-Type: application/json'

Personal API Token

First use the API Token to get an Access Token

curl --location -g --request POST '{csp-hostname}/csp/gateway/am/api/auth/api-tokens/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_token={api_token}'

Then use the Access Token to call Carbon Black Cloud APIs.

curl --location --request GET '{cbc-hostname}/{API Service Category}/{API path}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {csp-generated-access-token}'

If you are using VMware Cloud Services Platform in the UK PoP or AWS GovCloud (US), the X-Auth-Token method continues to be supported for backwards compatibility of existing integrations; enter your OAuth App Id and App Secret where the integration asks for API Id and API Key respectively. New integrations should be developed to support both X-Auth-Token authentication as well as OAuth Apps using a bearer and then access token.

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.

Determine the Identity Manager

There are two identity management solutions. In the UK Point of Presence (UK PoP or Prod UK) and AWS GovCloud (US), VMware Cloud Services Platform is deployed. Over time this will become an option in other environments.

If your app looks like this, then Carbon Black Cloud manages you identity and authentication

You know you use Carbon Black Cloud to manage identities and authentication in your environment if:

1. You log in through the Carbon Black Cloud Console:

2. On the top right menu you see a list which products are enabled and not

If your app looks like this, then VMware Cloud Services Platform manages my identity and authentication

You know you use VMware Cloud Services Platform to manage identities and authentication in your environment if:

1. You log in through the VMware Cloud Services Platform portal:

2. Within Carbon Black Cloud, from the top right hand corner a menu opens with VMware Cloud Services options.

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.

The first step of Authentication is determining the appropriate access level for the API. All APIs use an Access Level type of Custom.

Note: Some deprecated APIs used legacy Access Level types of API, LIVE_RESPONSE or SIEM. See Migration Guides for details of how to move to new APIs and take advantage of new Carbon Black Cloud features.

The Access Level Types of `API` and `LIVE_RESPONSE` will be deactivated in October 2024.

The Access Level Type of `SIEM` will be deactivated in January 2025.

More information about API and API Key deprecation and deactivation can be found in the Migration Guides.

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

Carbon Black Cloud Manages identities and roles

Create an Access Level

If your service category uses an API Key of type Custom, an Access Level with minimal permissions should be created to follow the practice of least privilege.

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.

Create 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

• 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).

VMware Cloud Services Manages identities and roles

See OAuth Access Control for steps to create a custom role and an OAuth app with those permissions.

Detail of managing roles and permissions using the Cloud Services Platform is in the Carbon Black Cloud User Guide.

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
Prod UK	https://ew2.carbonblackcloud.vmware.com

If you are using VMware Cloud Platform Services, this URL is the Carbon Black Cloud Console URL used after opening it via Services -> VMware Carbon Black Cloud > Launch Service.

Carbon Black Cloud Console URL from Cloud Services Platform

• The URL for VMware Cloud Services is
For UK Prod: https://console.cloud.vmware.com.
For AWS GovCloud (US): https://console.cloud-us-gov.vmware.com
• In VMware Cloud Services Console go to the Services menu on the left.
• Launch VMware Carbon Black Cloud.

• Get the URL when Carbon Black Cloud opens.

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 APIs
- recommendation-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	`/appservices/`	{hostname}/appservices/v6/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/v2/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}
Enriched Events Search	`/investigate/*`	{hostname}/investigate/{v1 or v2}/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.

Choose how to make the request.

If you use Carbon Black Cloud to manage identities then X-Auth-Token is your only option.
If you use Cloud Services Platform and are building scripts that you will run personally and should run with your privileges, then create a Personal API Token.
If you use Cloud Services Platform and are building an integration to connect Carbon Black Cloud with another application, use the OAuth App protocol.
If you use Cloud Services Platform and require the script to also be compatible with instances of Carbon Black Cloud that use Carbon Black Cloud to manage identities then also use the X-Auth-Token. Consider implementing this and the OAuth App protocol for forward looking compatibility.

Use the X-Auth-Token

This is the only way to call APIs if Carbon Black Cloud is used to manage roles and identities. If you use VMware Cloud Services Platform, this mechanism is supported for backwards compatibility. However, for new integrations it is recommended to use the OAuth App protocol described in the next option.

$ 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}}'

Use OAuth App credentials and then Access Token

The steps required to use the OAuth protocol are:
1. Make the API call with the OAuth App credentials to VMware Cloud Services Platform.
2. Make API calls to CBC APIs using the access token to perform functions as required.
3. Refresh the access token when the TTL expires

Full details, including creating an OAuth App are on the O-Auth Access page.

Use an API Token with personal permissions

1. Use the API Token to request an authentication token from the Cloud Services Platform. An authentication token will be returned in the response.

curl --location -g request POST '{csp-hostname}/csp/gateway/am/api/auth/api-tokens/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_token={api_token}'

2. Make the calls to Carbon Black Cloud APIs using the authorization token in the csp-auth-token header.
3. Refresh the authorization token when the TTL expires.

curl --location --request GET '{cbc-hostname}/{API Service Category}/{API path}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {csp-generated-access-token}'

See complete instructions in the VMware Cloud Services user guide in the section How do I generate API tokens.

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

The Access Level is type API, SIEM or LIVE_RESPONSE

The SIEM, API and LIVE_RESPONSE types were updated to map to fine grained RBAC permissions instead of hardcoded to specific API routes. Previously, a user role required only “Manage API Key” permissions to create or edit these roles. Now, a user must have the detailed permissions. These are:

Access Level Type SIEM

Note that the API that requires a SIEM type Access Level is deprecated and is planned for deactivation on October 31, 2024. Information about replacement APIs and how to migrate to them is in the Migration Guide.

Access Level Permission	Operations	User Role
Alerts > General information > org.alerts	READ	Alerts -> View Alerts, Notes, and Tags

Access Level Type API

Note that all APIs that require an API type Access Level are deprecated and are planned for deactivation on September 5, 2024. Information about replacement APIs and how to migrate to them is in the Migration Guide.

Access Level Permission	Operations	User Role
Audit Logs > View and Export Audits > org.audits	READ	Organization Settings -> View and Export Audit Logs
Custom Detections > Watchlists > org.watchlists	READ, CREATE, UPDATE, DELETE	Custom Detections -> View Watchlists and Manage Watchlists
Custom Detections > Feeds > org.feeds	READ, CREATE, UPDATE, DELETE	Custom Detections -> View Watchlist Feeds + Custom Detections -> Manage Watchlist Feeds
Device > General information > device	READ	Endpoint Management -> View Devices and Groups OR Endpoint Management -> Export Device Data
Device > Policy assignment > device.policy	UPDATE	Endpoint Management -> Manage Device Assignments
Policies > Policies > org.policies	READ, CREATE, UPDATE, DELETE	Policy Management -> Manage Policies
Search > Events > org.search.events	READ, CREATE, UPDATE, DELETE	Investigate -> Conduct Investigations
Unified Binary Store > SHA-256 > ubs.org.sha256	READ	Investigate -> Conduct Investigations OR Endpoint Management -> Get and Delete a Hash from Specified Devices
Unified Binary Store > File > ubs.org.file	READ	Endpoint Management -> Get and Delete a Hash from Specified Devices

Access Level Type LIVE_RESPONSE

Note that all APIs that require a LIVE_RESPONSE type Access Level are deprecated and are planned for deactivation on September 5, 2024. Information about replacement APIs and how to migrate to them is in the Migration Guide.

Access Level Permission	Operations	User Role
Audit Logs > View and Export Audits > org.audits	READ	Organization Settings -> View and Export Audit Logs
Device > General information > device	READ	Endpoint Management -> View Devices and Groups OR Endpoint Management -> Export Device Data
Device > Policy assignment > device.policy	UPDATE	Endpoint Management -> Manage Device Assignments
Live Response > Live Response Session > org.liveresponse.session	READ, CREATE	Live Response -> View Live Response OR Live Response -> Use Live Response
Live Response > Live Response Memory dump > org.liveresponse.memdump	DELETE	Live Response -> Dump Memory and Remove Live Response
Live Response > Disable Live Response > org.liveresponse	DELETE	Live Response -> Dump Memory and Remove Live Response
Live Response > Live Response File > org.liveresponse.file	READ, CREATE, DELETE	Live Response -> Use Live Response
Policies > Policies > org.policies	READ, CREATE, UPDATE, DELETE	Policy Management -> Manage Policies

Troubleshooting REST API Errors

HTTP 400 Bad request

Reason: Usually means that request contains unexpected parameters.
Suggested fix: Verify that your request adheres to API documentation.

HTTP 401 Unauthorized

Reason: Either authentication (invalid token) or access control (missing RBAC) error.
Suggested fix: Check that your X-Auth-Token matches the format secret_key/api_id and that the values are correct.

HTTP 403 Forbidden

Reason: The specified object cannot be accessed or changed.
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.

HTTP 404 Not found

Reason: The object referenced in the request cannot be found.
Suggested fix: Verify that your request contains objects that haven’t been deleted. Verify that the`org_key`in the path is correct.

HTTP 405 Method not allowed

Reason: The server knows the request method, but the target resource doesn’t support the method. This can be caused when the wrong verb is used (e.g. GET instead of POST) and there is no other call that uses that verb, the API route is incorrect, or the hostname is incorrect.
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.

HTTP 409 Conflict

Reason: Either the name you chose already exists, or there is an unacceptable character used.
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.

HTTP 410 Gone

Reason: Access to the target resource is no longer available at the origin server and that this condition is likely to be permanent.
Suggested fix: It is likely this API was deactivated. Review the documentation to find the replacement and migration information.

HTTP 503 Service unavailable

Reason: Cannot return object at this moment because service is unavailable.
Suggested fix: This can happen if too many file downloads are happening at the same time. You can try later.

HTTP 500 Internal Server Error

Reason: An unexpected error occurred on the server
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.

Last modified on September 21, 2023

Carbon Black Cloud

Page Contents