Endpoint Standard REST API

Carbon Black Cloud Endpoint Standard is the new name for the product formerly called CB Defense.

Authentication

Use the following information for authentication, and see the Carbon Black Cloud Authentication Guide for full instructions.

  • API Key: Authentication is handled by an API Secret Key and API ID, which are generated from the API Access page of the Carbon Black Cloud console. The API Secret Key and API ID are concatenated together to form the X-Auth-Token HTTP header, which is used to control access to the API. When generating the API keys, you will select an Access Level type from the dropdown.
  • The Access Level type for Audit Log Events is Custom.
  • Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL).
  • API Route: /integrationServices/v3/

Pagination

Most APIs are paginated so that large result sets can be returned to your API client in chunks. Every paginated API has the same standard request and response template.

When using a paginated API, the request includes two optional query parameters: start and rows. The start query parameter indicates the first row number that the API client expects from the result, and rows indicates the maximum number of rows that the API client expects in the response. Note that the maximum value of the rows parameter can be limited on the Endpoint Standard server side. The start value is based on a one-index. To retrieve the first 10 results of a result set, use start=1&rows=10.

The response payload also includes a totalResults value that indicates the total number of objects that matched the query.

Response Codes

  • HTTP 200: Successful response
  • HTTP 400: Bad request. Check the messages response for more information on errors encountered parsing the incoming payload.
  • HTTP 401: Unauthorized. Double check the X-Auth-Token authentication HTTP header to make sure that the Connector ID and API key are valid.
  • HTTP 404: Object not found. The requested object could not be found in the backend data store, or it may have expired (over 30 days old, etc.)
  • HTTP 429: Rate limiting encountered. Try again in a minute.
  • HTTP 500: Internal server error. Check the messages response for more information.
  • In addition, each message returns a boolean success indicator that indicates whether the operation was successful. The response contents should be further examined or processed only if the success indicator is true.

Audit Log Events

The integrationServices/v3/auditlogs API has been superseded by the platform-wide Audit Logs API

Migration information is available in the Migration Guide.

Retrieves all new audit log notifications since the last time the call was made with the same API Key ID. The response is a list of events in JSON format, sorted by time in ascending order (oldest notification first). Once a notification is viewed/ingested, it is cleared and will not be included in future responses to this API request.

In June 2023, the Audit Log API was updated to accept an API key of type Custom.

When you change to a new API key, the queue for reading audit logs will begin three days earlier. This may lead to duplicate data if Audit Log ingest was previously active with a different API key.

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/integrationServices/v3/auditlogs

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Audit Logs > View and Export Audits > org.audits, allow permission to READ

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.audits READ Majority of environments


Get Audit Log Events

The response will include various types of notifications such as:

  • Log in attempts by users
  • Updates to connectors
  • Creation of connectors
  • LiveResponse events

Request 
GET {cbc-hostname}/integrationServices/v3/auditlogs

Response Codes

Code Description Content-Type Content
200 Audit Logs correctly retrieved application/json See example below.
401 User is not Authenticated application\json 
{ "success": false,
  "message": "User is not authenticated" 
}

Examples

Request 
GET https://defense.conferdeploy.net/integrationServices/v3/auditlogs
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "notifications": [
        {
            "requestUrl": null,
            "eventTime": 1529332687006,
            "eventId": "37075c01730511e89504c9ba022c3fbf",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.3",
            "verbose": false,
            "description": "Logged in successfully"
        },
        {
            "requestUrl": null,
            "eventTime": 1529332689528,
            "eventId": "38882fa2730511e89504c9ba022c3fbf",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.3",
            "verbose": false,
            "description": "Logged in successfully"
        },
        {
            "requestUrl": null,
            "eventTime": 1529345346615,
            "eventId": "b0be64fd732211e89504c9ba022c3fbf",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.1",
            "verbose": false,
            "description": "Updated connector jason-splunk-test with api key Y8JNJZFBDRUJ2ZSM"
        },
        {
            "requestUrl": null,
            "eventTime": 1529345352229,
            "eventId": "b41705e7732211e8bd7e5fdbf9c916a3",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.2",
            "verbose": false,
            "description": "Updated connector Training with api key GRJSDHRR8YVRML3Q"
        },
        {
            "requestUrl": null,
            "eventTime": 1529345371514,
            "eventId": "bf95ae38732211e8bd7e5fdbf9c916a3",
            "loginName": "bs@carbonblack.com",
            "orgName": "example.org",
            "flagged": false,
            "clientIp": "192.0.2.2",
            "verbose": false,
            "description": "Logged in successfully"
        }
    ],
    "success": true,
    "message": "Success"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Last modified on March 20, 2025