You add and manage services integrations into your environment by setting their access level through API keys.

When creating your API Keys, you must take into account the following limitations and implications:

  • All current APIs use a key of type Custom. Create an Access Level that supports least privilege.
  • Types SIEM and API keys are deprecated and scheduled for deactivation on 31 October 2024 and 31 July 2024, respectively.
  • For API migration instructions, see API and Schema Migration (external link).
  • We recommend that new integrations use one of the following mechanisms to receive all available data:
    • Data Forwarders: to stream alerts or events to your own S3 bucket where you can control retention.
    • Alerts v7 API (external link): to search up to 180 days of historical alert data.
  • It is important that you safeguard the API ID and the API Secret key. The API Secret key is only displayed once at the time of creation and should be stored in a secure manner. It can be regenerated following the instructions to generate new credentials.

Prerequisites

To use the Custom access permissions for your integrations, you must create an access level. See Setting Access Levels.

Procedure

  1. On the left navigation pane, click Settings > API Access.
  2. For Custom API keys, create an access level. See Setting Access Levels.

    For more details, see the Carbon Black Cloud API Access (external link).

  3. Click Add API Key.
    Add an API custom key screenshot
    1. Enter a unique name and description.
    2. Select the appropriate Access Level Type. The default type is Custom.
    3. Set the Custom Access Level.
    4. Optional: Add authorized IP addresses.
      You can restrict the use of an API key to a specific set of IP addresses for security reasons.
  4. To apply the changes, click Save.

Results

A pop-up window displays the new API credentials:

API Credentials pop-up window after new API key has been generated.

What to do next

Purpose Action
To update the name, description, or the IP addresses for a specific API key: Click the Edit icon (pencil)Edit icon in the Actions column.
To generate new credentials: Click the Actions dropdown menu, select API credentials, and click Generate new API Secret Key.This API secret key is only displayed once and should be stored securely. This action will invalidate the prior existing API Secret key.
To see all notifications sent to the API key within a timeframe: Click the Actions dropdown menu, click Notification History, and then select the timeframe.
To delete the API key: Click the Actions dropdown menu and select Delete.
Note: You cannot use this procedure to delete API Keys that are associated with a notification rule. See Delete API Key with Attached Notification Rule.