User Management API


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:

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.

Role Permissions
Manage Users

Request

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

Response

Code Description Content-Type Content
200 List of Users fetched successfully. application/json View example response below

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.

Role Permissions
Manage Users

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

Field Definition Data Type Values
org_id Carbon Black Cloud Org ID Integer N/A
email
REQUIRED
User email String N/A
role
REQUIRED
User Role String Supported: DEPRECATED
role_urn User Role URN String Pattern:
psc:role:{org_key}:{role}
first_name User First Name String N/A
last_name User Last Name String N/A
created_by Created By String N/A
auth_method User Authentication Method String Supported: PASSWORD, SAML
profiles User Profiles Array Profiles Schema
phone User Phone String N/A

Response

Code Description Content-Type Content
201 Added User successfully to the org application/json View example response below
404 Invalid Orgnaization application/json
{
  "password": "string",
  "login_id": "string",
  "registration_type": "SUCCESS"
}
409 User already registered application/json
{
  "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.

Role Permissions
Manage Users

Request

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

Response

Code Description Content-Type Content
204 User deleted successfully. N/A N/A

Example

Request

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

Response

No Content


Modify User

Modify User.

Role Permissions
Manage Users

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

Field Definition Data Type Values
org_id
REQUIRED
Carbon Black Cloud Org ID Integer N/A
org_key Carbon Black Cloud Org Key String N/A
login_id
REQUIRED
User Login ID Integer N/A
login_name
REQUIRED
User Login Name String N/A
admin_login_version Admin Login Version Integer N/A
role
REQUIRED
User Role String Supported: DEPRECATED
org_admin_version Org Admin Version Integer N/A
first_name User First Name String N/A
last_name User Last Name String N/A
phone User Phone String N/A
email
REQUIRED
User email String N/A
contact_id
REQUIRED
Contact ID Integer N/A
contact_version Contact Version Integer N/A
auth_method User Auth Method String Supported: PASSWORD, SAML

Response

Code Description Content-Type Content
200 User updated successfully application/json N/A

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.

Role Permissions
Manage Users

Request

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

Response

Code Description Content-Type Content
204 Reset Google Authenticator registration application/json N/A
403 Forbidden N/A N/A

Example

Request

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

Response

No Content


Schemas

Profiles

Field Definition Data Type Values
orgs Organizations that access profile can manage Object
{
  "allow": [ "string" ]
}
roles Array containing User role information Array
[ "string" ]
conditions Object containing conditions for user roles Object
{
  "expiration": integer,
  "disabled": boolean
}

List Administrators Response

Field Definition Data Type Values
users Object containing User information Object Admin Summary Schema

Admin Summary

Field Definition Data Type Values
org_id
REQUIRED
Carbon Black Cloud Org ID Integer N/A
org_key Carbon Black Cloud Org Key String N/A
login_id
REQUIRED
User Login ID Integer N/A
login_name
REQUIRED
User Login Name String N/A
admin_login_version Admin Login Version Integer N/A
role
REQUIRED
User Role String Supported: DEPRECATED
org_admin_version Org Admin Version Integer N/A
first_name User First Name String N/A
last_name User Last Name String N/A
phone User Phone String N/A
email
REQUIRED
User email String N/A
contact_id
REQUIRED
Contact ID Integer N/A
contact_version Contact Version Integer N/A
auth_method User Auth Method String Supported: PASSWORD, SAML

Org Admin Registration Request

Field Definition Data Type Values
org_id Carbon Black Cloud Org ID Integer N/A
email
REQUIRED
User email String N/A
role
REQUIRED
User role String Supported: DEPRECATED
role_urn User role URN String Pattern:
psc:role:{org_key}:{role}
first_name User First Name String N/A
last_name User Last Name String N/A
created_by Created By String N/A
auth_method User Auth Method String N/A

Admin Registration Response

Field Definition Data Type Values
password Password Field String Default: null
success Status of request Boolean Supported: true, false
message Message of registration response String N/A
login_id User Login ID String Default: null
registration_status Registration Status String Supported: SUCCESS, DEVICE_ALREADY_REGISTERED, ERROR, COMPANY_ALREADY_REGISTERED, ADMIN_ALREADY_REGISTERED, DOMAIN_PROHIBITED, INVALID_EMAIL, REGISTRATION_ALREADY_CONFIRMED, INVALID_ORGANIZATION
Last modified on June 4, 2021