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 with identity managed within Carbon Black Cloud.
  • All API calls require an API key with appropriate permissions see Authentication

Note: If your organization uses VMware Cloud Services with Carbon Black Cloud, users and their permissions are managed in the VMware Cloud Services console and these APIs are not available. Further information is available in the VMware Carbon Black Cloud on VMware Cloud Services Platform. This includes all organizations using the UK point of presence (Prod UK) and AWS GovCloud (US).

Guides and Resources

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.

The API Key used to create users must have all the permissions being granted to the new users and “Manage Roles” and “Manage Users” from the “Organization Settings”.

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; and
    • All permissions to be granted to users
    • Some examples:
      • If you want the script to be able to create users with only View All role, the user-creating role needs all the permissions in View All and “Manage Roles” and “Manage Users”.
      • If you want the script to be able to create users with View All, Level 1 Analyst or Level 2 Analyst role, the user-creating role needs all the permissions in each of those three roles and “Manage Roles” and “Manage Users”.
    • This is to prevent privilege escalation and is the same restriction as the UI enforces: no user is able to create user accounts that have more permission than they already have. If a user could create a new user with additional permissions, they could then login with the new account, and have then increased their privileges with no authorisation.
  • It may be helpful to copy permissions from the standard role to be given to new users 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.

Environment Details:

Quick Start

Basic user creation with a grant

A Principal can be a User or an 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.
    Note: If you don’t want to assign a role when creating the user, you will need to manually Create the Grant with a follow-up API call.
  2. User receives an invitation in e-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.

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. Use the Get Permitted Roles API call to get the role_urns you can assign using your API key.

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 Organization 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"
}


Note: 'role' is now deprecated. Please use 'role_urn' to assign roles when creating API users. For more information about role assignment, use the API calls below to retrieve roles for existing users.

Get Grant of Principal
Bulk Fetch Grants

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


Fields

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 February 13, 2023