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.
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).
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
Option 2
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:
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.
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
}
]
}
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 |
|
409 | User already registered | application/json |
|
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 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.
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.
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
Field | Definition | Data Type | Values |
---|---|---|---|
orgs |
Organizations that access profile can manage | Object |
|
roles |
Array containing User role information | Array |
|
conditions |
Object containing conditions for user roles | Object |
|
Field | Definition | Data Type | Values |
---|---|---|---|
users |
Object containing User information | Object | Admin Summary 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 |
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 |
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 |