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:

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

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.
User receives an invitation in e-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.

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

Carbon Black Cloud

Page Contents

User Management API

Overview

Requirements

Guides and Resources

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