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).

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.

Create a new user with Level 1 Analyst role by using Create User API call.
User receives an invite in mail and Follows instructions for registration.
Check if the new user is included in the Organization by using the List All Users API call.
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

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 July 20, 2022

Carbon Black Cloud

Page Contents

User Management API

Overview

Requirements

Authentication

Quick Start

Basic user creation with a grant

API Calls

List All Users

Create User

Delete User

Modify User

Reset Google Authenticator Registration

Fields

Profiles

List Administrators Response

Admin Summary

Org Admin Registration Request

Admin Registration Response