Overview

This API lets you create and manage user accounts in the Carbon Black Cloud for one or more CBC Organizations. Every user is assigned to a role. Roles contain varying sets of permissions which dictate the views and actions available to a user.

Requirements

• At least one Carbon Black Cloud product
• All API calls require an API key with appropriate permissions see Authentication

Authentication

Access Level and API Key:

When creating your API Key, this API requires a different process for creating the appropriate Access Level than is outlined in the Carbon Black Cloud Authentication Guide.

Option 1

• Navigate to Settings > API Access in the Carbon Black Cloud console, and add a new API Key with a “Custom” Access Level and choose “Super Admin” from the Custom Access Level dropdown. This will grant the maximum permissions to the API Key and allow the key to grant any role.

Option 2

• It is recommended to limit access to only the necessary permissions, so the “Super Admin” Access Level may not be right for you. To create a new Access Level with more limited permissions:
  • Navigate to Settings > Roles in the console.
  • Add a new Role and then use the category expanders to add permissions to the role. At minimum, you must add the permissions for “Manage Roles” and “Manage Users” from the “Organization Settings” category. It may be helpful to copy permissions from the “Level 3 Analyst” and add the “Manage Roles” and “Manage Users” permissions on top of the base permissions for that role.
  • Once you configure the role to your liking, hit save, and then add a new API Key from Settings > API Access, select “Custom” Access Level, and choose the new role from the Custom Access Level dropdown.

Note: you can only create Roles with the same level of permissions granted to you. You may need a Super Admin to assist in creating the new Role and API Key.

Environment Details:

• Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)
• API Route: {cbc-hostname}/appservices/v6/orgs/{org_key}/users
  • Example: https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/users

Quick Start

Basic user creation with a grant

A Principal can be User or API Key. In this example the Principal is a User. Check the Access Profiles and Grants API for more details on Grants.

1. Create a new user with Level 1 Analyst role by using Create User API call.
2. User receives an invite in mail and Follows instructions for registration.
3. Check if the new user is included in the Organization by using the List All Users API call.
4. View the details of the User Grant with the Get Grant of a Principal call from the Access Profiles and Grants API.

API Calls

List All Users

List all users in an Organization.

Request

GET {cbc-hostname}/appservices/v6/orgs/{org_key}/users

Response

Example

Request

GET https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/users

Response

{
    "success": true,
    "message": "Success",
    "users": [
        {
            "org_key": "ABCD1234",
            "auth_method": "PASSWORD",
            "org_id": 12345678,
            "login_id": 4865950,
            "login_name": "demo@vmware.com",
            "email": "demo@vmware.com",
            "phone": "",
            "first_name": "John",
            "last_name": "Smith",
            "admin_login_version": 2,
            "org_admin_version": 0,
            "role": "DEPRECATED",
            "contact_id": 16077588,
            "contact_version": 0
        }
    ]
}

Create User

Request to register a user and link them to an Organization.

Request

POST {cbc-hostname}/appservices/v6/orgs/{org_key}/users

Request Body - application/json

{
    "org_id": integer,
    "email": "string",
    "role": "string",
    "role_urn": "string",
    "first_name": "string",
    "last_name": "string",
    "created_by": "string",
    "auth_method": "string",
    "phone": "string,"
    "profiles": [
        {
            "orgs": {
                "allow": [
                    "string"
                ]
            },
            "roles": [
                "string"
            ],
            "conditions": {
                "expiration": integer,
                "disabled": boolean
            }
        }
    ]
}

Body Schema

Response

{
  "password": "string",
  "login_id": "string",
  "registration_type": "SUCCESS"
}

{
  "password": "string",
  "login_id": "string",
  "registration_type": "SUCCESS"
}

Example

Request

POST https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/users

Request_Body

{
    "email": "demo@vmware.com",
    "role": "DEPRECATED",
    "role_urn": "psc:role:ABCD1234:LEVEL_1_ANALYST_WITH_MANAGE_USERS",
    "profiles": [
        {
            "orgs": {
                "allow": [ "psc:org:ABCD1234" ]
            },
            "roles": [ "psc:role:ABCD1234:LEVEL_1_ANALYST_WITH_MANAGE_USERS" ]
        }
    ],
    "first_name": "John",
    "last_name": "Smith",
    "auth_method": "PASSWORD"
}

Response

{
    "password": null,
    "success": true,
    "message": "Success",
    "login_id": null,
    "registration_status": "SUCCESS"
}

Delete User

Delete a user.

Request

DELETE {cbc-hostname}/appservices/v6/orgs/{org_key}/users/{login_id}

Response

Example

Request

DELETE https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/users/12345678

Response

No Content

Modify User

Modify User.

Request

PUT {cbc-hostname}/appservices/v6/orgs/{org_key}/users/{login_id}

Request Body - application/json

{
  "org_id": integer,
  "org_key": "string",
  "login_id": integer,
  "login_name": "string",
  "admin_login_version": integer,
  "role": "string",
  "org_admin_version": integer,
  "first_name": "string",
  "last_name": "string",
  "phone": "string",
  "email": "string",
  "contact_id": integer,
  "contact_version": integer,
  "auth_method": "string"
}

Body Schema

Response

Example

Request

PUT https://defense-eap01.conferdeploy.net/appservices/v6/orgs/ABCD1234/users/12345678

Request_Body

{
    "org_id": 1234567,
    "org_key": "ABCD1234",
    "login_id": 12345678,
    "login_name": "demo@vmware.com",
    "admin_login_version": 4,
    "role": "DEPRECATED",
    "org_admin_version": 0,
    "first_name": "John",
    "last_name": "Smith",
    "phone": "12345678",
    "email": "demo@vmware.com",
    "contact_id": 16087983,
    "contact_version": 0,
    "auth_method": "PASSWORD"
}

Response

{
    "modifiedByAnotherUser": false,
    "success": true,
    "message": "Success"
}

Reset Google Authenticator Registration

Reset Google Authenticator Registration.

Request

DELETE {cbc-hostname}/appservices/v6/orgs/{org_key}/users/{login_id}/google-auth

Response

Example

Request

DELETE https://defense-eap01.conferdeploy.net/ABCD1234/users/12345678/google-auth

Response

No Content

Schemas

Profiles

{
  "allow": [ "string" ]
}

[ "string" ]

{
  "expiration": integer,
  "disabled": boolean
}

List Administrators Response

Admin Summary

Org Admin Registration Request

Admin Registration Response