Carbon Black User Management API Guide

Auth method: API Key (custom connector key passed as HTTP header: X-Auth-Token: /)

Setup steps

1. Log in to the Carbon Black Cloud console as an administrator.
2. Navigate to Settings > API Access > API Keys.
3. Click 'Add API Key', select the access level type (e.g., Custom, SIEM, Live Response, Device Control).
4. Copy the API Secret Key and API ID shown at creation (secret is shown only once).
5. Construct the auth header: X-Auth-Token: /.
6. Include the org_key (found in Settings > API Access) in all API request URLs.

Required scopes

List Users

• Method: GET
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/users
• Watch out for: Requires org.users READ permission on the API key. Returns all users in the org; no server-side filtering by role is documented.

Request example

GET /appservices/v6/orgs/ABCD1234/users
X-Auth-Token: <secret>/<id>

Response example

{
  "users": [
    {"user_id": 123, "login_id": "user@example.com", "first_name": "Jane", "last_name": "Doe", "role": "ANALYST", "status": "ACTIVE"}
  ],
  "num_found": 1
}

Get User

• Method: GET
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/users/<user_id>
• Watch out for: user_id is a numeric integer, not the email/login_id. Must be obtained from the list endpoint first.

Request example

GET /appservices/v6/orgs/ABCD1234/users/123
X-Auth-Token: <secret>/<id>

Response example

{
  "user_id": 123,
  "login_id": "user@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "ANALYST",
  "status": "ACTIVE"
}

Create User

• Method: POST
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/users
• Watch out for: Newly created users receive a PENDING_ACTIVATION status until they complete email verification. SSO users may bypass this depending on org IdP config.

Request example

POST /appservices/v6/orgs/ABCD1234/users
Content-Type: application/json
{
  "login_id": "newuser@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "role": "ANALYST"
}

Response example

{
  "user_id": 456,
  "login_id": "newuser@example.com",
  "status": "PENDING_ACTIVATION"
}

Update User

• Method: PATCH
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/users/<user_id>
• Watch out for: login_id (email) cannot be changed after creation. Only mutable fields like role, first_name, last_name, phone can be updated.

Request example

PATCH /appservices/v6/orgs/ABCD1234/users/456
Content-Type: application/json
{
  "role": "ADMINISTRATOR"
}

Response example

{
  "user_id": 456,
  "role": "ADMINISTRATOR",
  "status": "ACTIVE"
}

Delete User

• Method: DELETE
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/users/<user_id>
• Watch out for: Deletion is immediate and irreversible. The user_id cannot be reused. Deleting the last admin user is blocked by the API.

Request example

DELETE /appservices/v6/orgs/ABCD1234/users/456
X-Auth-Token: <secret>/<id>

Response example

HTTP 204 No Content

Get User Grants (Roles/Permissions)

• Method: GET
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/users/<user_id>/grants
• Watch out for: Grants are separate from the base user object. Role changes via the grants endpoint may differ from the role field on the user object in multi-org setups.

Request example

GET /appservices/v6/orgs/ABCD1234/users/123/grants
X-Auth-Token: <secret>/<id>

Response example

{
  "grants": [
    {"role": "ANALYST", "org_key": "ABCD1234"}
  ]
}

List API Keys

• Method: GET
• URL: https://<hostname>/appservices/v6/orgs/<org_key>/apiaccess/key
• Watch out for: API secret values are never returned after initial creation. This endpoint only lists key metadata.

Request example

GET /appservices/v6/orgs/ABCD1234/apiaccess/key
X-Auth-Token: <secret>/<id>

Response example

{
  "results": [
    {"id": "KEYID1", "name": "My Key", "access_level_type": "CUSTOM", "status": "ENABLED"}
  ]
}

• Rate limits: Carbon Black Cloud does not publicly document specific numeric rate limits for the Users API. General API throttling is applied per org and per API key.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No publicly documented rate limit tiers or headers found. Broadcom/VMware support should be consulted for enterprise-specific limits. HTTP 429 is returned when throttled.

• Pagination method: offset

• Default page size: 20

• Max page size: 200

• Pagination pointer: rows / start

• Webhooks available: No

• Webhook notes: Carbon Black Cloud does not offer native outbound webhooks for user management events (user created, deleted, role changed). Event notifications are available for security alerts via the Alerts API and S3/syslog notification channels, but not for user lifecycle events.

• Alternative event strategy: Poll the Users API on a schedule to detect changes. For security events, use CBC Notifications (S3 bucket, syslog, or webhook) configured in the console under Settings > Notifications.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Carbon Black Cloud does not natively support SCIM 2.0 provisioning.
• User provisioning via IdPs (Okta, Entra ID, OneLogin) must be done through SSO/SAML JIT provisioning or manual API scripting.
• No SCIM endpoint is documented in the official CBC developer portal.
• Enterprise plan and SSO configuration are prerequisites for any automated provisioning approach.

Three primary automation scenarios are well-supported by the documented API. First, provisioning: POST to /users with login_id, first_name, last_name, and role; the user enters PENDING_ACTIVATION status until email verification completes - SSO orgs may bypass this via IdP login instead.

Second, deprovisioning: retrieve the numeric user_id via the list endpoint (email-based lookup is not directly supported), then DELETE /users/. note there is no suspend or disable state via API - deletion is the only option, and it is immediate and irreversible.

Third, role elevation: PATCH /users/ with the target role string; role names are case-sensitive and only built-in roles (ADMINISTRATOR, ANALYST, READ_ONLY_ANALYST) are documented as API-assignable - custom console roles may not be settable via API.

A critical offboarding caveat: API keys are scoped separately from user accounts and must be revoked via the /apiaccess/key endpoint independently; deleting a user does not revoke their keys.

Provision a new analyst user

1. Obtain a Custom API key with org.users CREATE permission from Settings > API Access.
2. POST to /appservices/v6/orgs//users with login_id (email), first_name, last_name, and role=ANALYST.
3. Capture the returned user_id for future reference.
4. User receives an activation email; status transitions from PENDING_ACTIVATION to ACTIVE upon completion.
5. Optionally verify by GET /appservices/v6/orgs//users/ to confirm status=ACTIVE.

Watch out for: If the org uses SSO/SAML, the user may need to log in via the IdP first to complete activation rather than via the email link.

Deprovision a departing user

1. Use GET /appservices/v6/orgs//users to find the user by email (login_id) and retrieve their user_id.
2. Confirm the user is not the last administrator in the org.
3. DELETE /appservices/v6/orgs//users/.
4. Expect HTTP 204 on success; the user is immediately removed.

Watch out for: There is no 'disable' or 'suspend' state via API - deletion is the only deprovisioning action. If audit trail retention is needed, document the user record before deletion.

Elevate a user's role to Administrator

1. Retrieve the user's user_id via GET /appservices/v6/orgs//users.
2. PATCH /appservices/v6/orgs//users/ with body {"role": "ADMINISTRATOR"}.
3. Verify the change with GET /appservices/v6/orgs//users/ and confirm role=ADMINISTRATOR.

Watch out for: Role names are case-sensitive and must match CBC's predefined role strings exactly. Custom roles defined in the console may not be assignable via API - only built-in roles are documented as supported.

Several non-obvious constraints make DIY Carbon Black Cloud API integration fragile in production. The org_key (alphanumeric string) and org_id (integer) are distinct identifiers and are not interchangeable in URLs - using the wrong one returns errors that may not clearly indicate the mismatch.

Hostnames are region-specific (e.g., defense-eu.conferdeploy.net for EU orgs) and must be hardcoded correctly per environment. No rate limit values are publicly documented; HTTP 429 is returned when throttled, but there are no Retry-After headers to guide backoff logic.

Webhooks are not available for user lifecycle events, so detecting changes requires scheduled polling of the list endpoint. Post-Broadcom acquisition, documentation URLs are in active reorganization, and some VMware-era developer portal links redirect inconsistently - treat any cached API reference as potentially stale.