Public Cloud Account Management API


Overview

VMware Carbon Black Cloud Workload for Public Cloud provides the ability to secure AWS workloads while simplifying the overhead of AWS account management. Core capabilities include:

  • Single and multiple AWS account management.
  • Auto-generated CI-CD agent installation packages.
  • Enhanced visibility into inventory of protected and unprotected workloads.

Prior to the Carbon Black Cloud Workload for Public Cloud, Amazon EC2 instances were treated as Endpoints. We recommend updating the Carbon Black sensor to the latest sensor version prior to enabling the Carbon Black Cloud Workload for Public Cloud. These sensors can also be upgraded after the Carbon Black Cloud Workload for Public Cloud is enabled.

Requirements

  • Carbon Black Cloud Workload - You must have purchased one of the Carbon Black Cloud Workload packages.
  • Minimum sensor versions: Version: 3.8 (Windows) & 2.13 (Linux). Check they’re the correct sensor version.

Resources

AWS Account Management

Infosec and AWS administrators can easily manage their AWS accounts and regions. They can:

  • Add a single account.
  • Leverage bulk import of accounts to facilitate quick onboarding of existing AWS accounts.
  • Search and export onboarded AWS accounts and regions into an easy-to-consume format.

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Account Management: {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts
  • Bulk Account Management: {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/cloud_providers
  • Configuration Template: {cbc-hostname}/public-cloud/account-management/v1/accounts/import/template
  • Account Management: {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/account_actions
  • Cloud Provider Information: {cbc-hostname}/public-cloud/account-management/v1/cloud_providers/{cloud_provider}

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Public Cloud > Manage public cloud accounts > public.cloud.accounts, allow permission to CREATE, READ, UPDATE, DELETE, EXECUTE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • Account Management: {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts
  • Bulk Account Management: {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/cloud_providers
  • Configuration Template: {cbc-hostname}/public-cloud/account-management/v1/accounts/import/template
  • Account Management: {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/account_actions
  • Cloud Provider Information: {cbc-hostname}/public-cloud/account-management/v1/cloud_providers/{cloud_provider}

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Public.Cloud:Public.cloud.accounts:CREATE, allow permission to CREATE, READ, UPDATE, DELETE, EXECUTE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


API Calls

Onboard New Cloud Account


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts CREATE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:CREATE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts


Request Body - application/json 

{
  "cloud_provider_account_id": "<string>",
  "cloud_provider": "<string>",
  "name": "<string>",
  "owner_name": "<string>",
  "owner_email": "<string>",
  "environment": "<string>",
  "credential": {
    "role_arn": "<string>",
    "external_id": "<string>"
  },
  "regions": ["<string>"],
  "created_by": "<string>",
  "updated_by": "<string>",
  "event_stream_status": "<string>"
}

Body Schema

Field Definition Data Type Values
cloud_provider_account_id REQUIRED Account id of the cloud provider String N/A
cloud_provider REQUIRED Public cloud provider (e.g. AWS) String N/A
name REQUIRED Name for the account String N/A
owner_name REQUIRED Owner name String N/A
owner_email REQUIRED Owner email String N/A
environment REQUIRED Environment String DEV, STAGING, TEST, PROD
credential REQUIRED Credential of account to access customer environment Object Credential
regions REQUIRED List of region ids for account Array Possible regions can be retrieved with Get Details of a Cloud Provider
created_by Created By String N/A
updated_by Updated By String N/A
event_stream_status Event stream setup status String ENABLED, DISABLED, PARTIALLY_ENABLED

Response

Code Description Content-Type Content
200 Account successfully created. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
409 Already Exists N/A 
{
  "error_code": null,
  "follow_up_api": null,
  "message": "Account Already Exist",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/accounts
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "cloud_provider_account_id": "1234567890",
  "cloud_provider": "AWS",
  "name": "AWS Account 1",
  "owner_name": "Test",
  "owner_email": "test@testorg.com",
  "environment": "DEV",
  "credential": {
    "role_arn": "arn:aws:iam::1234567890:role/aws-service-role/spot.amazonaws.com/AWSServiceRoleForEC2Spot",
    "external_id": "QWERTY"
  },
  "regions": [
    "us-east-1",
    "us-east-2"
  ]
}
Response Body 
{
  "cloud_provider_account_id": "1234567890",
  "cloud_provider": "AWS",
  "name": "AWS Account 1",
  "owner_name": "Test",
  "owner_email": "test@testorg.com",
  "environment": "DEV",
  "credential": {
    "role_arn": "arn:aws:iam::1234567890:role/aws-service-role/spot.amazonaws.com/AWSServiceRoleForEC2Spot",
    "external_id": "QWERTY",
    "verification_status": "IN_PROGRESS",
    "verification_code": null,
    "verification_message": null,
    "last_verified_time": "2021-08-26T09:26:37.937Z"
  },
  "last_updated_time": "2022-07-21T12:47:01.292Z",
  "regions": [
    "us-east-1",
    "us-east-2"
  ],
  "created_by": "ABCD123456",
  "updated_by": "ABCD123456",
  "event_stream_status": "DISABLED"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Cloud Account


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts UPDATE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

PUT {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/cloud_providers/{cloud_provider}/accounts/{cloud_provider_account_id}


Request Body - application/json 

{
  "cloud_provider_account_id": "<string>",
  "cloud_provider": "<string>",
  "name": "<string>",
  "owner_name": "<string>",
  "owner_email": "<string>",
  "environment": "<string>",
  "credential": {
    "role_arn": "<string>",
    "external_id": "<string>"
  },
  "regions": ["<string>"],
  "created_by": "<string>",
  "updated_by": "<string>",
  "event_stream_status": "<string>"
}

Body Schema

Field Definition Data Type Values
cloud_provider_account_id REQUIRED Account id of the cloud provider String N/A
cloud_provider REQUIRED Public cloud provider (e.g. AWS) String N/A
name REQUIRED Name for the account String N/A
owner_name REQUIRED Owner name String N/A
owner_email REQUIRED Owner email String N/A
environment REQUIRED Environment String DEV, STAGING, TEST, PROD
credential REQUIRED Credential of account to access customer environment Object Credential
regions REQUIRED List of region ids for account Array Possible regions can be retrieved with Get Details of a Cloud Provider
created_by Created By String N/A
updated_by Updated By String N/A
event_stream_status Event stream setup status String ENABLED, DISABLED, PARTIALLY_ENABLED

Response

Code Description Content-Type Content
200 Account successfully updated. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
404 Account Not Found N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Account Not Found",
    "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
PUT https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/cloud_providers/AWS/accounts/1234567890
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "cloud_provider_account_id": "1234567890",
  "cloud_provider": "AWS",
  "name": "AWS Account 1",
  "owner_name": "Test",
  "owner_email": "test@testorg.com",
  "environment": "DEV",
  "credential": {
    "role_arn": "arn:aws:iam::1234567890:role/aws-service-role/spot.amazonaws.com/AWSServiceRoleForEC2Spot",
    "external_id": "QWERTY"
  },
  "regions": [
    "us-east-1",
    "us-east-2"
  ]
}
Response Body 
{
  "cloud_provider_account_id": "1234567890",
  "cloud_provider": "AWS",
  "name": "AWS Account 1",
  "owner_name": "Test",
  "owner_email": "test@testorg.com",
  "environment": "DEV",
  "credential": {
    "role_arn": "arn:aws:iam::1234567890:role/aws-service-role/spot.amazonaws.com/AWSServiceRoleForEC2Spot",
    "external_id": "QWERTY",
    "verification_status": "IN_PROGRESS",
    "verification_code": null,
    "verification_message": null,
    "last_verified_time": "2021-08-26T09:26:37.937Z"
  },
  "last_updated_time": "2022-07-21T12:47:01.292Z",
  "regions": [
    "us-east-1",
    "us-east-2"
  ],
  "created_by": "ABCD123456",
  "updated_by": "ABCD123456",
  "event_stream_status": "DISABLED"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Cloud Account by Id


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

GET {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/cloud_providers/{cloud_provider}/accounts/{cloud_provider_account_id}

Response

Code Description Content-Type Content
200 Account successfully retrieved. application/json View example response below
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
404 Account Not Found N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Account Not Found",
    "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
GET https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/cloud_providers/AWS/accounts/1234567890
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "cloud_provider_account_id": "1234567890",
  "cloud_provider": "AWS",
  "name": "AWS Account 1",
  "owner_name": "Test",
  "owner_email": "test@testorg.com",
  "environment": "DEV",
  "credential": {
    "role_arn": "arn:aws:iam::1234567890:role/aws-service-role/spot.amazonaws.com/AWSServiceRoleForEC2Spot",
    "external_id": "QWERTY",
    "verification_status": "IN_PROGRESS",
    "verification_code": null,
    "verification_message": null,
    "last_verified_time": "2021-08-26T09:26:37.937Z"
  },
  "last_updated_time": "2022-07-21T12:47:01.292Z",
  "regions": [
    "us-east-1",
    "us-east-2"
  ],
  "created_by": "ABCD123456",
  "updated_by": "ABCD123456",
  "event_stream_status": "DISABLED"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Cloud Account

Delete onboarded account from Carbon Black Cloud.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts DELETE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:DELETE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

DELETE {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/cloud_providers/{cloud_provider}/accounts/{cloud_provider_account_id}

Response

Code Description Content-Type Content
204 Account successfully deleted. N/A No content
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
404 Account Not Found N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Account Not Found",
    "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
DELETE https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/cloud_providers/AWS/accounts/1234567890
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
No content
To download or review the Carbon Black Cloud Postman collection, click here.

Bulk Delete Cloud Accounts

Bulk delete multiple onboarded accounts from Carbon Black Cloud.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts DELETE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:DELETE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts/_delete


Request Body - application/json 

[
  {
    "cloud_provider_account_id": "<string>",
    "cloud_provider": "<string>"
  }
]

Body Schema

Field Definition Data Type Values
account_ids REQUIRED Account id of the cloud provider Array Account Id

Response

Code Description Content-Type Content
200 Accounts successfully deleted. application/json View example response below
200 Data is correct, but some accounts were not deleted successfully. application/json 
{
    "error_code": null,
    "failed": [
        {
            "cloud_provider": "AWS",
            "cloud_provider_account_id": "1234567890"
        }
    ],
    "follow_up_api": null,
    "message": "Delete for few accounts failed. Check failed field for the same.",
    "success": false
}
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/accounts/_delete
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
  {
    "cloud_provider_account_id": "1234567890",
    "cloud_provider": "AWS"
  },
  {
    "cloud_provider_account_id": "1234567891",
    "cloud_provider": "AWS"
  }
]
Response Body 
{
    "error_code": null,
    "failed": null,
    "follow_up_api": null,
    "message": "Successful",
    "success": true
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Cloud Accounts


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts/_search


Request Body - application/json 

{
  "start": <integer>,
  "rows": <integer>,
  "query": "<string>",
  "criteria": {
    "name": [ "<string>" ],
    "cloud_provider": [ "<string>" ],
    "cloud_provider_account_id": [ "<string>" ],
    "credential.verification_status": [ "<string>" ],
    "environment": [ "<string>" ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}

Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
  "name": [
    "Account Name"
  ]
}
Supported fields: name, cloud_provider, cloud_provider_account_id, credential.verification_status, environment
query Query in lucene syntax and/or including value searches. String N/A
rows REQUIRED Maximum number of rows to return Integer Max: 10k
start REQUIRED What row to begin returning results from Integer
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "name",
  "order": "asc"
}]
order supports asc or desc

Supported Fields: credential.last_verified_time, name, cloud_provider, cloud_provider_account_id, owner_email, last_updated_time, environment

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/accounts/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "start": 0,
  "rows": 0,
  "criteria": {
    "name": [
      "AWS Account 1"
    ],
    "cloud_provider": [
      "AWS"
    ],
    "cloud_provider_account_id": [
      "1234567890",
      "1234567891"
    ],
    "credential.verification_status": [
      "IN_PROGRESS",
      "SUCCESS",
      "FAIL"
    ],
    "environment": [
      "DEV",
      "PROD"
    ]
  },
  "sort": [
    {
      "field": "credential.last_verified_time",
      "order": "ASC"
    }
  ]
}
Response Body 
{
    "num_found": 1,
    "results": [
        {
            "cloud_provider": "AWS",
            "cloud_provider_account_id": "1234567890",
            "created_by": "ABCD123456",
            "credential": {
                "external_id": "QWERTY",
                "last_verified_time": "2022-07-25T13:22:47.303694Z",
                "role_arn": "arn:aws:iam::1234567890:user/test.com",
                "verification_code": "AWS_CREDENTIAL_ERROR",
                "verification_message": "message",
                "verification_status": "FAIL"
            },
            "environment": "DEV",
            "event_stream_status": "DISABLED",
            "last_updated_time": "2022-07-25T13:22:46.905086Z",
            "name": "AWS Account 1",
            "owner_email": "test@vmware.com",
            "owner_name": "Test",
            "updated_by": "ABCD123456"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Cloud Accounts


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts/_search/download


Request Body - application/json

Refer to Search Cloud Accounts Request

Response

Code Description Content-Type Content
200 Successful Search Request. text/csv View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/accounts/_search/download
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "start": 0,
  "rows": 0,
  "criteria": {
    "name": [
      "AWS Account 1"
    ],
    "cloud_provider": [
      "AWS"
    ],
    "cloud_provider_account_id": [
      "1234567890",
      "1234567891"
    ],
    "credential.verification_status": [
      "IN_PROGRESS",
      "SUCCESS",
      "FAIL"
    ],
    "environment": [
      "DEV",
      "PROD"
    ]
  },
  "sort": [
    {
      "field": "credential.last_verified_time",
      "order": "ASC"
    }
  ]
}
Response Body 
orgKey,accountId,accountProvider,region,accountName,accountOwnerName,accountOwnerEmail,environment,credentialRoleArn,credentialExternalId,credentialVerificationStatus,credentialVerificationCode,credentialVerificationMessage,credentialLastVerifiedTime,createTime,createdBy,updateTime,updatedBy,regionEventChannelTemplateVersion,regionEventChannelConnected,regionEventChannelLastConnectedTime,regionEventChannelCreatedTime,regionEventChannelUpdatedTime,regionInventorySyncStatus,regionInventorySyncMessage,regionInventorySyncCode,regionInventoryLastSyncTime,regionInventoryFullSyncBy,regionCreatedTime,regionCreatedBy
TEST,1234567890,AWS,us-east-1,AWS Account 1,Test,test@testorg.com,DEV,arn:aws:iam::1234567890:user/test@testorg.com,QWERTY,FAIL,AWS_CREDENTIAL_ERROR,"error message",2022-07-25T13:22:47.303694Z,2022-07-25T13:22:46.905086Z,ABCD123456,2022-07-25T13:22:46.905086Z,ABCD123456,,false,,,,NOT_STARTED,,,,,2022-07-25T13:22:46.909939Z,ABCD123456
To download or review the Carbon Black Cloud Postman collection, click here.

Import Cloud Accounts by CSV


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts CREATE, UPDATE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:CREATE, UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts/import


Request Body - text/csv

accountId,accountProvider,accountName,accountOwnerName,accountOwnerEmail,environment,credentialRoleArn,credentialExternalId,regions\r\n
1234567890,AWS,AWS Account 1,Test,test@testorg.com,DEV,arn:aws:iam::1234567890:user/test@testorg.com,QWERTY,us-east-1

Response

Code Description Content-Type Content
200 Successful import request. application/json 
{
  "success": true,
  "message": "Accounts uploaded successfully"
}
400 The csv file is malformed N/A 
{
  "success": false,
  "error_code": "FIELD_MISSING",
  "message": "Required field is missing"
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/accounts/import
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "text/csv"
Request Body 
accountId,accountProvider,accountName,accountOwnerName,accountOwnerEmail,environment,credentialRoleArn,credentialExternalId,regions\r\n
1234567890,AWS,AWS Account 1,Test,test@testorg.com,DEV,arn:aws:iam::1234567890:user/test@testorg.com,QWERTY,us-east-1
Response Body 
{
  "success": true,
  "message": "Accounts uploaded successfully"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Download Cloud Account Import Template


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts CREATE, UPDATE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:CREATE, UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

GET {cbc-hostname}/public-cloud/account-management/v1/accounts/import/template


Response

Code Description Content-Type Content
200 Successfully retrieved template. text/csv View example response below
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
GET https://defense.conferdeploy.net/public-cloud/account-management/v1/accounts/import/template
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
accountId,accountProvider,accountName,accountOwnerName,accountOwnerEmail,environment,credentialRoleArn,credentialExternalId,regions
To download or review the Carbon Black Cloud Postman collection, click here.

Perform Action on Multiple Accounts


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts EXECUTE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:EXECUTE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/account_actions


Request Body - application/json 

{
  "accounts": [
    {
      "cloud_provider_account_id": "<string>",
      "cloud_provider": "<string>",
      "regions": [ "<string>" ]
    }
  ],
  "action_type": "<string>"
}

Body Schema

Field Definition Data Type Values
accounts REQUIRED Accounts with a list of regions Array Account Action
action_type REQUIRED Action to be performed String SYNC_INVENTORY

Response

Code Description Content-Type Content
200 Action successfully performed. application/json View example response below
202 Action accepted. application/json 
{
  "follow_up_api": "/orgs/TESTORG/accounts/_search",
  "message": "Sync action initiated successfully",
  "success": true
}
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/account_actions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "accounts": [
    {
      "cloud_provider_account_id": "333",
      "cloud_provider": "AWS"
    },
    {
      "cloud_provider_account_id": "444",
      "cloud_provider": "AWS",
      "regions": [
        "us-east-01",
        "us-east-02"
      ]
    }
  ],
  "action_type": "SYNC_INVENTORY"
}
Response Body 
[
  {
    "count": 1,
    "result": [
      {
        "cloud_provider_account_id": "155093827112",
        "cloud_provider": "AWS",
        "regions": null,
        "action_status": false,
        "action_message": "Role validation failed"
      }
    ]
  }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Validate Account Roles


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts EXECUTE Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:EXECUTE N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/accounts/validate_role


Request Body - application/json 

[
  {
    "cloud_provider_account_id": "<string>",
    "cloud_provider": "<string>",
    "saved_credentials": <boolean>,
    "role_arn": "<string>",
    "external_id": "<string>"
  }
]

Body Schema

Field Definition Data Type Values
accounts REQUIRED List of accounts with credentials details Array Account Validate Role

Response

Code Description Content-Type Content
200 Role validated. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
POST https://defense.conferdeploy.net/public-cloud/account-management/v1/orgs/ABCD1234/accounts/validate_role
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
[
  {
    "cloud_provider_account_id": "555",
    "cloud_provider": "AWS",
    "saved_credentials": false,
    "role_arn": "SomeValidArn",
    "external_id": "SomeValidExternalId"
  },
  {
    "cloud_provider_account_id": "666",
    "cloud_provider": "AWS",
    "saved_credentials": true
  }
]
Response Body 
[
  {
    "cloud_provider_account_id": "555",
    "cloud_provider": "AWS",
    "validation_status": true,
    "validation_code": "OK",
    "validation_message": ""
  },
  {
    "cloud_provider_account_id": "666",
    "cloud_provider": "AWS",
    "validation_status": false,
    "validation_code": "AWS_CREDENTIAL_ERROR",
    "validation_message": "Role ARN is invalid"
  }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Get Details of a Cloud Provider


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

GET {cbc-hostname}/public-cloud/account-management/v1/cloud_providers/{cloud_provider}

Response

Code Description Content-Type Content
200 Information successfully retrieved. application/json View example response below
400 Cloud Provider Not Found N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
GET https://defense.conferdeploy.net/public-cloud/account-management/v1/cloud_providers/AWS
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "environments": [
        "DEV",
        "STAGING",
        "TEST",
        "PROD"
    ],
    "onboarding_powershell_script_url": "https://.../aws/powershell/Setup-cbc-events-stream.ps1",
    "onboarding_shell_script_url": "https://.../aws/shell/setup-cbc-event-stream.sh",
    "regions": [
        {
            "id": "us-east-1",
            "name": "US East (N. Virginia)"
        },
        {
            "id": "us-east-2",
            "name": "US East (Ohio)"
        },
        ...
    ],
    "trust_relationship_setup_details": {
        "aws_collector_arn": "arn:aws:iam::...",
        "powershell_script_url": "https://.../aws/trust-relationship/powershell/Setup-trust-relationship.ps1",
        "shell_script_url": "https://.../aws/trust-relationship/shell/setup-trust-relationship.sh"
    }
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Regions for a Cloud Account


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.accounts READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.accounts:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

GET {cbc-hostname}/public-cloud/account-management/v1/orgs/{org_key}/cloud_providers/{cloud_provider}/accounts/{cloud_provider_account_id}/regions

Response

Code Description Content-Type Content
200 Information successfully retrieved. application/json View example response below
400 Cloud Provider is not valid. N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
404 Account Not Found N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Account Not Found",
    "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "Some internal server error occurred",
  "success": false
}

Examples

Request 
GET https://defense.conferdeploy.net/account-management/v1/orgs/ABCD1234/cloud_providers/AWS/accounts/1234567890/regions
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
[
  {
    "id": "us-east-1",
    "name": "US East (N. Virginia)",
    "event_channel": {
      "template_version": "1.0.0",
      "connected": false,
      "last_connected_time": "2022-07-25T17:09:12.325Z",
      "create_time": "2022-07-25T17:09:12.325Z",
      "update_time": "2022-07-25T17:09:12.325Z"
    },
    "inventory_sync": {
      "status": "NOT_STARTED",
      "message": "some message",
      "code": "",
      "synced_by": "5024999",
      "last_sync_time": "2022-07-25T17:09:12.325Z"
    },
    "create_time": "2022-07-25T17:09:12.325Z",
    "created_by": "5024999"
  }
]
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Account

Field Definition Data Type Values
cloud_provider_account_id REQUIRED Account id of the cloud provider String N/A
cloud_provider REQUIRED Public cloud provider (e.g. AWS) String N/A
name REQUIRED Name for the account String N/A
owner_name REQUIRED Owner name String N/A
owner_email REQUIRED Owner email String N/A
environment REQUIRED Environment String DEV, STAGING, TEST, PROD
credential REQUIRED Credential of account to access customer environment Object Credential
regions REQUIRED List of region ids for account Array Possible regions can be retrieved with Get Details of a Cloud Provider
created_by String N/A
updated_by String N/A
event_stream_status Event stream setup status String ENABLED, DISABLED, PARTIALLY_ENABLED
last_updated_time Timestamp of the last update String N/A

Credential

Field Definition Data Type Values
role_arn AWS related credential connector property String N/A
external_id AWS related credential unique external id String N/A

Credential Response

Field Definition Data Type Values
role_arn AWS related credential connector property String N/A
external_id AWS related credential unique external id String N/A
verification_status Verification status of the creation of the account String NOT_STARTED, IN_PROGRESS, SUCCESS, FAIL, TIMED_OUT
verification_code Verification code of the creation of the account String N/A
verification_message Verification message of the creation of the account String N/A
last_verified_time Last verified time String N/A

Account Id

Field Definition Data Type Values
cloud_provider_account_id REQUIRED Account id of the cloud provider String N/A
cloud_provider REQUIRED Public cloud provider (e.g. AWS) String N/A

Account Action

Field Definition Data Type Values
cloud_provider_account_id REQUIRED Account id of the cloud provider String N/A
cloud_provider REQUIRED Public cloud provider (e.g. AWS) String N/A
regions List of region ids for account Array Possible regions can be retrieved with Get Regions for a Cloud Account

Account Action Response

Field Definition Data Type Values
cloud_provider_account_id Account id of the cloud provider String N/A
cloud_provider Public cloud provider (e.g. AWS) String N/A
regions List of region ids for account Array N/A
action_status Result of the action performed Boolean true, false
action_message Message for the result of the action performed String N/A

Account Validate Role

Field Definition Data Type Values
cloud_provider_account_id REQUIRED Account id of the cloud provider String N/A
cloud_provider REQUIRED Public cloud provider (e.g. AWS) String N/A
saved_credentials REQUIRED Flag whether to save the credentials Boolean true, false
role_arn AWS related credential connector property String N/A
external_id AWS related credential unique external id String N/A

Cloud Provider Response

Field Definition Data Type Values
regions List of available regions Array N/A
environments Environments Array DEV, STAGING, TEST, PROD
onboarding_shell_script_url Onboarding shell script URL String N/A
onboarding_powershell_script_url Onboarding powershell script URL String N/A
trust_relationship_setup_details Details to setup trust relationship between customer AWS account and CB account Object Trust Relationship Setup Details

Trust Relationship Setup Details

Field Definition Data Type Values
shell_script_url Shell script URL for the script that can setup trust relationship String N/A
powershell_script_url PowerShell script URL for the script that can setup trust relationship String N/A
aws_collector_arn Environment specific ARN of AWS String N/A

Region Details Response

Field Definition Data Type Values
id Unique id of the region (provided by cloud provider) String N/A
name Name of the region (provided by cloud provider) String N/A
event_channel Details of event channel setup Object Event Channel Setup
inventory_sync Inventory sync details Object Inventory Sync Details
create_time create time String N/A
created_by User id or connector id of the one who added this region to the account String N/A

Event Channel Setup

Field Definition Data Type Values
template_version Version of event channel template deployed on the region String N/A
connected connected flag String true, false
last_connected_time Last connected time String N/A
create_time Create time String N/A
update_time Update time String N/A

Inventory Sync Details

Field Definition Data Type Values
status Status of the inventory sync String NOT_STARTED, IN_PROGRESS, SUCCESS, FAIL, TIMED_OUT
message Message for the status of the operation String N/A
code Code for the status of the operation N/A
synced_by Synced by String N/A
last_sync_time Last sync time String N/A

Give Feedback

Use this form to give us feedback about this site or any of the documentation.


Last modified on September 6, 2022