Enterprise Management | IBM Cloud API Docs

Introduction

Last updated: 2022-11-04

With the Enterprise Management API, you can create and manage IBM Cloud® enterprises. An enterprise is a hierarchical account structure that you can use to centrally manage billing and usage across multiple IBM Cloud accounts. You can recreate your organizational structure in the cloud, with billing consolidated across all accounts to the enterprise level.

In an enterprise, you can import existing accounts from outside the enterprise or create new accounts within the enterprise, and then organize the accounts by using account groups. To create a multitiered hierarchy, you can nest account groups within an account group. See What is an enterprise? for more information about how enterprises can simplify your account management.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Java SDK

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>enterprise-management</artifactId>
    <version>{version}</version>
</dependency>
Copy to clipboard

Gradle

compile 'com.ibm.cloud:enterprise-management:{version}'

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-java-sdk

Installing the Go SDK

Installation

go get -u github.com/IBM/platform-services-go-sdk/enterprisemanagementv1

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-go-sdk

Installing the Node SDK

Installation

npm install @ibm-cloud/platform-services

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

Installation

pip install --upgrade "ibm-platform-services"

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The Enterprise Management API uses the following global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://enterprise.cloud.ibm.com

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL for VPC infrastructure: https://private.enterprise.cloud.ibm.com
Private endpoint URLs for classic infrastructure:
- Dallas: https://private.us-south.enterprise.cloud.ibm.com
- Washington DC: https://private.us-east.enterprise.cloud.ibm.com

Example API request

curl -X {request_method} "https://enterprise.cloud.ibm.com/{method_endpoint}"

Replace {request_method} and {method_endpoint} in this example with the values for your particular API call.

Authentication

Authorization to the Enterprise Management REST API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that the identity has access to when using various Enterprise API services. Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM Token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer $TOKEN'.

Adequate access is required to use the API. Each method lists the IAM action that you need to be assigned access to. The access control is hierarchical, which means that granting access to an entity in the enterprise hierarchy also grants access to its children. For example, if you grant a user access to the Enterprise service on an account group, the user also has that access on the accounts and account groups in it. For more information, see Assigning enterprise access.

To create an enterprise, you must have the Administrator role on the Billing service in the account. After the enterprise is created, a user with the Administrator or Editor on the Enterprise service can update enterprise properties, such as the name or domain, of the enterprise. A user with the Viewer role on the Enterprise service can retrieve and list the enterprise, account groups, and accounts within the enterprise.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey={api_key}'
Copy to clipboard

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

Example that sets options by using environment variables

export ENTERPRISE_MANAGEMENT_APIKEY={api_key}

import com.ibm.cloud.platform_services.enterprise_management.v1.EnterpriseManagement;

EnterpriseManagement enterpriseManagementService = EnterpriseManagement.newInstance();
Copy to clipboard

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterpriseManagementService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export ENTERPRISE_MANAGEMENT_APIKEY={api_key}

enterpriseManagementService, err := enterprisemanagementv1.NewEnterpriseManagementV1UsingExternalConfig(
        &enterprisemanagementv1.EnterpriseManagementV1Options{})
if err != nil {
    panic(err)
}
Copy to clipboard

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterpriseManagementService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export ENTERPRISE_MANAGEMENT_APIKEY={api_key}

from ibm_platform_services import  EnterpriseManagementV1
enterprise_management_service =  EnterpriseManagementV1.new_instance()

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterprise_management_service variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export ENTERPRISE_MANAGEMENT_APIKEY={api_key}

const EnterpriseManagementV1 = require('ibm-platform-services/enterprise-management/v1');

const enterpriseManagementService = EnterpriseManagementV1.newInstance({});
Copy to clipboard

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterpriseManagementService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. When some API methods are called, an event is generated that you can then track and audit from within Activity Tracker. For methods that generate events, the specific event type is listed for each individual method.

For more information about how to track activity in an enterprise, see Auditing events for account management.

Error handling

The Enterprise Management API returns standard HTTP status codes to indicate the success or failure of a request. The response is in JSON format as shown in the following example:

{
    "message": "Not Authenticated",
    "trace": "27249289915",
    "errors": [
        {
            "code": "invalid_token",
            "message": "Not Authenticated",
            "target": {
                "type": "",
                "name": ""
            }
        }
    ]
}

The server returns an appropriate error code when a particular operation can't be fulfilled. All responses from the Enterprise Management API are in JSON format.

The API can return the following error codes.

HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`201`	Created	The resource was successfully created.
`204`	No Content	The request was successful. No response body is provided.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again.
`403`	Forbidden	The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions.
`404`	Not Found	The requested resource could not be found.
`409`	Conflict	The entity is already in the requested state.
`429`	Too Many Requests	Too many requests were made within a period of time. Wait before you call the API again.
`500`	Internal Server Error	The API had an internal server error and could not process the request.
`503`	Service Temporarily Unavailable	The API or one of its internal dependent services is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

/v1/enterprises
/v1/enterprises?enterprise_account_id={account_id}
/v1/enterprises?enterprise_id={enterprise_id}&next_docid={next_docid}
/v1/enterprises?account_group_id={account_group_id}
/v1/enterprises?account_id={account_id}
/v1/account-groups
/v1/account-groups?enterprise_id={enterprise_id}
/v1/account-groups?account_group_id={account_group_id}&next_docid={next_docid}
/v1/account-groups?parent_account_group_id={account_group_id}
/v1/account-groups?parent={parent_crn}
/v1/accounts
/v1/accounts?enterprise_id={enterprise_id}
/v1/accounts?account_id={account_id}&next_docid={next_docid}
/v1/accounts?account_group_id={account_group_id}
/v1/accounts?parent={parent_crn}

The rows_count, next_url and resources fields are included in the collection response. The next_url field gives the link to the next page of results.

The default page size is 100 items, which is also the maximum size of responses on a page. To use a different page size, use the limit query parameter.

The rows_count field indicates the number of resources that exist on the page.

Rate limiting

Rate limits for API requests are enforced on a per-caller basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

X-RateLimit-Reset: The time the current timer expires (in UNIX epoch time)
X-RateLimit-Remaining: The number of requests that are remaining in the current time window
X-RateLimit-Limit: The total number of requests allowed within the time window

An HTTP status code of 429 indicates that the rate limit was exceeded.

The number of allowed requests, and the length of the time window, might vary by method and endpoint. The reference information for each endpoint specifies the rate limit that applies.

When you work with the Enterprise API endpoints, it might be helpful to be familiar with the following related APIs:

Enterprise Usage Reports API: Get usage reports for an enterprise, account group, or account.
Enterprise Billing Units API: Manage enterprise billing and credit pools.
Unified Account Management API: Get account information and invite users.
Resource Controller API: Manage resource instances, keys, bindings, and more.

Create a new enterprise, which you can use to centrally manage multiple accounts. To create an enterprise, you must have an active Subscription account.

The API creates an enterprise entity, which is the root of the enterprise hierarchy. It also creates a new enterprise account that is used to manage the enterprise. All subscriptions, support entitlements, credits, and discounts from the source subscription account are migrated to the enterprise account, and the source account becomes a child account in the hierarchy. The user that you assign as the enterprise primary contact is also assigned as the owner of the enterprise account.

POST /enterprises

(enterpriseManagement *EnterpriseManagementV1) CreateEnterprise(createEnterpriseOptions *CreateEnterpriseOptions) (result *CreateEnterpriseResponse, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) CreateEnterpriseWithContext(ctx context.Context, createEnterpriseOptions *CreateEnterpriseOptions) (result *CreateEnterpriseResponse, response *core.DetailedResponse, err error)

ServiceCall<CreateEnterpriseResponse> createEnterprise(CreateEnterpriseOptions createEnterpriseOptions)
Copy to clipboard

createEnterprise(params)

create_enterprise(self,
        source_account_id: str,
        name: str,
        primary_contact_iam_id: str,
        *,
        domain: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.enterprise.create

Auditing

Calling this method generates the following auditing event.

enterprise.enterprise.create

Request

Instantiate the CreateEnterpriseOptions struct and set the fields to provide parameter values for the CreateEnterprise method.

Use the CreateEnterpriseOptions.Builder to create a CreateEnterpriseOptions object that contains the parameter values for the createEnterprise method.

Request Body

Required*

CreateEnterpriseRequest

The body required to create an enterprise.

parameter

WithContext method only

CreateEnterpriseOptions

The CreateEnterprise options.

CreateEnterpriseOptions

The createEnterprise options.

parameters

sourceAccountId
Required*
string
The ID of the account that is used to create the enterprise.
name
Required*
string
The name of the enterprise. This field must have 3 - 60 characters.
primaryContactIamId
Required*
string
The IAM ID of the enterprise primary contact, such as IBMid-0123ABC. The IAM ID must already exist.
domain
string
A domain or subdomain for the enterprise, such as example.com or my.example.com.

parameters

source_account_id
Required*
str
The ID of the account that is used to create the enterprise.
name
Required*
str
The name of the enterprise. This field must have 3 - 60 characters.
primary_contact_iam_id
Required*
str
The IAM ID of the enterprise primary contact, such as IBMid-0123ABC. The IAM ID must already exist.
domain
str
A domain or subdomain for the enterprise, such as example.com or my.example.com.

Example request

curl -X POST "https://enterprise.cloud.ibm.com/v1/enterprises -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "source_account_id": "a1b2c32a5ea94809a9840f5e23c362d",
  "name": "Example Enterprise",
  "domain": "example.com",
  "primary_contact_iam_id": "IBMid-0123ABC"
}'
Copy to clipboard

Example request

createEnterpriseOptions := enterpriseManagementService.NewCreateEnterpriseOptions(
  srcAccountID,
  "Example Enterprise",
  contactIamID,
)

createEnterpriseResponse, response, err := enterpriseManagementService.CreateEnterprise(createEnterpriseOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createEnterpriseResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateEnterpriseOptions createEnterpriseOptions = new CreateEnterpriseOptions.Builder()
    .sourceAccountId(srcAccountId)
    .name("Example Enterprise")
    .primaryContactIamId(contactIamId)
    .build();

Response<CreateEnterpriseResponse> response = enterpriseManagementService.createEnterprise(createEnterpriseOptions).execute();
CreateEnterpriseResponse createEnterpriseResponse = response.getResult();

System.out.println(createEnterpriseResponse);

Example request

const params = {
  sourceAccountId: srcAccountId,
  name: 'Example Enterprise',
  primaryContactIamId: contactIamId,
};

try {
  const res = await enterpriseManagementService.createEnterprise(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

create_enterprise_response = enterprise_management_service.create_enterprise(
  source_account_id=src_account_id,
  name='Example Enterprise',
  primary_contact_iam_id=contact_iam_id,
).get_result()

print(json.dumps(create_enterprise_response, indent=2))
Copy to clipboard

Response

Response Body

CreateEnterpriseResponse

The response from calling create enterprise

CreateEnterpriseResponse

The response from calling create enterprise.

CreateEnterpriseResponse

The response from calling create enterprise.

CreateEnterpriseResponse

The response from calling create enterprise.

CreateEnterpriseResponse

The response from calling create enterprise.

Status Code

202
Enterprise is now in 'PENDING' state. Enterprise state will update to 'ACTIVE' when asynchronous processing is complete
400
Bad Request
401
Invalid or Expired Access Token
403
Access Denied
500
Internal Server Error
503
Service Unavailable

Example responses

Status 202

{
  "enterprise_id": "$ENTERPRISE_ID",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID"
}
Copy to clipboard

Success example

{
  "enterprise_id": "$ENTERPRISE_ID",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID"
}
Copy to clipboard

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 500

Error example

Status 503

Error example

Retrieve all enterprises for a given ID by passing the IDs on query parameters. If no ID is passed, the enterprises for which the calling identity is the primary contact are returned. You can use pagination parameters to filter the results.

This method ensures that only the enterprises that the user has access to are returned. Access can be controlled either through a policy on a specific enterprise, or account-level platform services access roles, such as Administrator, Editor, Operator, or Viewer. When you call the method with the enterprise_account_id or account_id query parameter, the account ID in the token is compared with that in the query parameter. If these account IDs match, authentication isn't performed and the enterprise information is returned. If the account IDs don't match, authentication is performed and only then is the enterprise information returned in the response.

GET /enterprises

(enterpriseManagement *EnterpriseManagementV1) ListEnterprises(listEnterprisesOptions *ListEnterprisesOptions) (result *ListEnterprisesResponse, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) ListEnterprisesWithContext(ctx context.Context, listEnterprisesOptions *ListEnterprisesOptions) (result *ListEnterprisesResponse, response *core.DetailedResponse, err error)

ServiceCall<ListEnterprisesResponse> listEnterprises(ListEnterprisesOptions listEnterprisesOptions)
Copy to clipboard

listEnterprises(params)

list_enterprises(self,
        *,
        enterprise_account_id: str = None,
        account_group_id: str = None,
        account_id: str = None,
        next_docid: str = None,
        limit: int = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.enterprise.retrieve

Request

Instantiate the ListEnterprisesOptions struct and set the fields to provide parameter values for the ListEnterprises method.

Use the ListEnterprisesOptions.Builder to create a ListEnterprisesOptions object that contains the parameter values for the listEnterprises method.

Query Parameters

enterprise_account_id
string
Get enterprises for a given enterprise account ID.
account_group_id
string
Get enterprises for a given account group ID.
account_id
string
Get enterprises for a given account ID.
next_docid
string
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
limit
integer
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
Default: 100

parameter

WithContext method only

ListEnterprisesOptions

The ListEnterprises options.

ListEnterprisesOptions

The listEnterprises options.

parameters

enterpriseAccountId
string
Get enterprises for a given enterprise account ID.
accountGroupId
string
Get enterprises for a given account group ID.
accountId
string
Get enterprises for a given account ID.
nextDocid
string
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
limit
number
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100

parameters

enterprise_account_id
str
Get enterprises for a given enterprise account ID.
account_group_id
str
Get enterprises for a given account group ID.
account_id
str
Get enterprises for a given account ID.
next_docid
str
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
limit
int
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100

Example request

curl -X GET "https://enterprise.cloud.ibm.com/v1/enterprises" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

listEnterprisesOptions := &enterprisemanagementv1.ListEnterprisesOptions{
  EnterpriseAccountID: &enterpriseAccountID,
}

pager, err := enterpriseManagementService.NewEnterprisesPager(listEnterprisesOptions)
if err != nil {
  panic(err)
}

var allResults []enterprisemanagementv1.Enterprise
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListEnterprisesOptions listEnterprisesOptions = new ListEnterprisesOptions.Builder()
  .enterpriseAccountId(enterpriseAccountId)
  .build();

EnterprisesPager pager = new EnterprisesPager(enterpriseManagementService, listEnterprisesOptions);
List<Enterprise> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<Enterprise> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  accountId: enterpriseAccountId,
};

const allResults = [];
try {
  const pager = new EnterpriseManagementV1.EnterprisesPager(enterpriseManagementService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = EnterprisesPager(
  client=enterprise_management_service,
  account_id=enterprise_account_id,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

ListEnterprisesResponse

The response from calling list enterprises

ListEnterprisesResponse

The response from calling list enterprises.

ListEnterprisesResponse

The response from calling list enterprises.

ListEnterprisesResponse

The response from calling list enterprises.

ListEnterprisesResponse

The response from calling list enterprises.

Status Code

200
Success
401
Invalid or Expired Access Token
403
Access Denied
500
Internal Server Error
503
Service Unavailable

Example responses

Status 200

{
  "rows_count": 1,
  "next_url": "/v1/enterprises?$ENTERPRISE_ID&next_docid=$NEXT_DOCID",
  "resources": [
    {
      "url": "/v1/enterprises/$ENTERPRISE_ID",
      "id": "$ENTERPRISE_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
      "name": "Sample Enterprise",
      "domain": "example.com",
      "state": "ACTIVE",
      "primary_contact_iam_id": "IBMid-0123ABC",
      "primary_contact_email": "user@example.com",
      "source_account_id": "a1b2c32a5ea94809a9840f5e23c362d",
      "created_at": "2019-05-14T19:46:51.522Z",
      "updated_at": "2019-05-14T19:46:54.437Z",
      "created_by": "iam-ServiceId-c8dae",
      "updated_by": "iam-ServiceId-bfe3d"
    }
  ]
}
Copy to clipboard

Success example

{
  "rows_count": 1,
  "next_url": "/v1/enterprises?$ENTERPRISE_ID&next_docid=$NEXT_DOCID",
  "resources": [
    {
      "url": "/v1/enterprises/$ENTERPRISE_ID",
      "id": "$ENTERPRISE_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
      "name": "Sample Enterprise",
      "domain": "example.com",
      "state": "ACTIVE",
      "primary_contact_iam_id": "IBMid-0123ABC",
      "primary_contact_email": "user@example.com",
      "source_account_id": "a1b2c32a5ea94809a9840f5e23c362d",
      "created_at": "2019-05-14T19:46:51.522Z",
      "updated_at": "2019-05-14T19:46:54.437Z",
      "created_by": "iam-ServiceId-c8dae",
      "updated_by": "iam-ServiceId-bfe3d"
    }
  ]
}
Copy to clipboard

Status 401

Error example

Status 403

Error example

Status 500

Error example

Status 503

Error example

Retrieve an enterprise by the enterprise_id parameter. All data related to the enterprise is returned only if the caller has access to retrieve the enterprise.

GET /enterprises/{enterprise_id}

(enterpriseManagement *EnterpriseManagementV1) GetEnterprise(getEnterpriseOptions *GetEnterpriseOptions) (result *Enterprise, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) GetEnterpriseWithContext(ctx context.Context, getEnterpriseOptions *GetEnterpriseOptions) (result *Enterprise, response *core.DetailedResponse, err error)

ServiceCall<Enterprise> getEnterprise(GetEnterpriseOptions getEnterpriseOptions)
Copy to clipboard

getEnterprise(params)

get_enterprise(self,
        enterprise_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.enterprise.retrieve

Request

Instantiate the GetEnterpriseOptions struct and set the fields to provide parameter values for the GetEnterprise method.

Use the GetEnterpriseOptions.Builder to create a GetEnterpriseOptions object that contains the parameter values for the getEnterprise method.

Path Parameters

enterprise_id
Required*
string
The ID of the enterprise to retrieve.

parameter

WithContext method only

GetEnterpriseOptions

The GetEnterprise options.

GetEnterpriseOptions

The getEnterprise options.

parameters

enterpriseId
Required*
string
The ID of the enterprise to retrieve.

parameters

enterprise_id
Required*
str
The ID of the enterprise to retrieve.

Example request

curl -X GET "https://enterprise.cloud.ibm.com/v1/enterprises/$ENTERPRISE_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

getEnterpriseOptions := enterpriseManagementService.NewGetEnterpriseOptions(
  enterpriseID,
)

enterprise, response, err := enterpriseManagementService.GetEnterprise(getEnterpriseOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(enterprise, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetEnterpriseOptions getEnterpriseOptions = new GetEnterpriseOptions.Builder()
    .enterpriseId(enterpriseId)
    .build();

Response<Enterprise> response = enterpriseManagementService
    .getEnterprise(getEnterpriseOptions)
    .execute();
Enterprise enterprise = response.getResult();

System.out.println(enterprise);

Example request

const params = {
  enterpriseId: enterpriseId,
};

try {
  const res = await enterpriseManagementService.getEnterprise(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

enterprise = enterprise_management_service.get_enterprise(enterprise_id=enterprise_id).get_result()

print(json.dumps(enterprise, indent=2))

Response

Response Body

Enterprise

An enterprise resource

Enterprise

An enterprise resource.

Enterprise

An enterprise resource.

Enterprise

An enterprise resource.

Enterprise

An enterprise resource.

Status Code

200
Successfully retrieved enterprise by ID
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 200

{
  "url": "/v1/enterprises/$ENTERPRISE_ID",
  "id": "$ENTERPRISE_ID",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
  "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
  "name": "Sample Enterprise",
  "domain": "example.com",
  "state": "ACTIVE",
  "primary_contact_iam_id": "IBMid-0123ABC",
  "primary_contact_email": "user@example.com",
  "source_account_id": "a1b2c32a5ea94809a9840f5e23c362d",
  "created_at": "2019-05-14T19:46:51.522Z",
  "updated_at": "2019-05-14T19:46:54.437Z",
  "created_by": "iam-ServiceId-c8dae",
  "updated_by": "iam-ServiceId-bfe3d"
}
Copy to clipboard

Success example

{
  "url": "/v1/enterprises/$ENTERPRISE_ID",
  "id": "$ENTERPRISE_ID",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
  "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
  "name": "Sample Enterprise",
  "domain": "example.com",
  "state": "ACTIVE",
  "primary_contact_iam_id": "IBMid-0123ABC",
  "primary_contact_email": "user@example.com",
  "source_account_id": "a1b2c32a5ea94809a9840f5e23c362d",
  "created_at": "2019-05-14T19:46:51.522Z",
  "updated_at": "2019-05-14T19:46:54.437Z",
  "created_by": "iam-ServiceId-c8dae",
  "updated_by": "iam-ServiceId-bfe3d"
}
Copy to clipboard

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Update the name, domain, or IAM ID of the primary contact for an existing enterprise. The new primary contact must already be a user in the enterprise account.

PATCH /enterprises/{enterprise_id}

(enterpriseManagement *EnterpriseManagementV1) UpdateEnterprise(updateEnterpriseOptions *UpdateEnterpriseOptions) (response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) UpdateEnterpriseWithContext(ctx context.Context, updateEnterpriseOptions *UpdateEnterpriseOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> updateEnterprise(UpdateEnterpriseOptions updateEnterpriseOptions)
Copy to clipboard

updateEnterprise(params)

update_enterprise(self,
        enterprise_id: str,
        *,
        name: str = None,
        domain: str = None,
        primary_contact_iam_id: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.enterprise.update

Auditing

Calling this method generates the following auditing event.

enterprise.enterprise.update

Request

Instantiate the UpdateEnterpriseOptions struct and set the fields to provide parameter values for the UpdateEnterprise method.

Use the UpdateEnterpriseOptions.Builder to create a UpdateEnterpriseOptions object that contains the parameter values for the updateEnterprise method.

Path Parameters

enterprise_id
Required*
string
The ID of the enterprise to retrieve.

Request Body

Required*

UpdateEnterpriseRequest

Parameters to update the enterprise.

parameter

WithContext method only

UpdateEnterpriseOptions

The UpdateEnterprise options.

UpdateEnterpriseOptions

The updateEnterprise options.

parameters

enterpriseId
Required*
string
The ID of the enterprise to retrieve.
name
string
The new name of the enterprise. This field must have 3 - 60 characters.
domain
string
The new domain of the enterprise. This field has a limit of 60 characters.
primaryContactIamId
string
The IAM ID of the user to be the new primary contact for the enterprise.

parameters

enterprise_id
Required*
str
The ID of the enterprise to retrieve.
name
str
The new name of the enterprise. This field must have 3 - 60 characters.
domain
str
The new domain of the enterprise. This field has a limit of 60 characters.
primary_contact_iam_id
str
The IAM ID of the user to be the new primary contact for the enterprise.

Example request

curl -X PATCH "https://enterprise.cloud.ibm.com/v1/enterprises/$ENTERPRISE_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "name": "Updated Example Enterprise",
  "domain": "new.example.com"
}'
Copy to clipboard

Example request

updateEnterpriseOptions := enterpriseManagementService.NewUpdateEnterpriseOptions(
  enterpriseID,
)
updateEnterpriseOptions.SetName("Updated Example Enterprise")
updateEnterpriseOptions.SetPrimaryContactIamID(enterpriseAccountIamID)

response, err := enterpriseManagementService.UpdateEnterprise(updateEnterpriseOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UpdateEnterpriseOptions updateEnterpriseOptions = new UpdateEnterpriseOptions.Builder()
    .enterpriseId(enterpriseId)
    .name("Updated Example Enterprise")
    .build();

Response<Void> response = enterpriseManagementService.updateEnterprise(updateEnterpriseOptions)
    .execute();

Example request

const params = {
  enterpriseId: enterpriseId,
  name: 'Updated Example Enterprise',
  primaryContactIamId: enterpriseAccountIamId,
};

try {
  await enterpriseManagementService.updateEnterprise(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = enterprise_management_service.update_enterprise(
  enterprise_id=enterprise_id,
  name='Updated Example Enterprise',
  primary_contact_iam_id=enterprise_account_iam_id,
)

Response

Status Code

204
Success
400
Bad Request. The payload passed to the request is invalid.
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Import an existing stand-alone account into an enterprise. The existing account can be any type: trial (TRIAL), Lite (STANDARD), Pay-As-You-Go (PAYG), or Subscription (SUBSCRIPTION). In the case of a SUBSCRIPTION account, the credits, promotional offers, and discounts are migrated to the billing unit of the enterprise. For a billable account (PAYG or SUBSCRIPTION), the country and currency code of the existing account and the billing unit of the enterprise must match. The API returns a 202 response and performs asynchronous operations to import the account into the enterprise.

For more information about impacts to the account, see Adding accounts to an enterprise.

PUT /enterprises/{enterprise_id}/import/accounts/{account_id}

(enterpriseManagement *EnterpriseManagementV1) ImportAccountToEnterprise(importAccountToEnterpriseOptions *ImportAccountToEnterpriseOptions) (response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) ImportAccountToEnterpriseWithContext(ctx context.Context, importAccountToEnterpriseOptions *ImportAccountToEnterpriseOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> importAccountToEnterprise(ImportAccountToEnterpriseOptions importAccountToEnterpriseOptions)
Copy to clipboard

importAccountToEnterprise(params)

import_account_to_enterprise(self,
        enterprise_id: str,
        account_id: str,
        *,
        parent: str = None,
        billing_unit_id: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.enterprise.import

Auditing

Calling this method generates the following auditing event.

enterprise.enterprise.import

Request

Instantiate the ImportAccountToEnterpriseOptions struct and set the fields to provide parameter values for the ImportAccountToEnterprise method.

Use the ImportAccountToEnterpriseOptions.Builder to create a ImportAccountToEnterpriseOptions object that contains the parameter values for the importAccountToEnterprise method.

Path Parameters

enterprise_id
Required*
string
The ID of the enterprise to import the stand-alone account into.
account_id
Required*
string
The ID of the existing stand-alone account to be imported.

Request Body

ImportToEnterpriseRequest

The body of the request to import an account into the enterprise.

parameter

WithContext method only

ImportAccountToEnterpriseOptions

The ImportAccountToEnterprise options.

ImportAccountToEnterpriseOptions

The importAccountToEnterprise options.

parameters

enterpriseId
Required*
string
The ID of the enterprise to import the stand-alone account into.
accountId
Required*
string
The ID of the existing stand-alone account to be imported.
parent
string
The CRN of the expected parent of the imported account. The parent is the enterprise or account group that the account is added to.
billingUnitId
string
The ID of the billing unit to use for billing this account in the enterprise.

parameters

enterprise_id
Required*
str
The ID of the enterprise to import the stand-alone account into.
account_id
Required*
str
The ID of the existing stand-alone account to be imported.
parent
str
The CRN of the expected parent of the imported account. The parent is the enterprise or account group that the account is added to.
billing_unit_id
str
The ID of the billing unit to use for billing this account in the enterprise.

Example request

curl -X PUT "https://enterprise.cloud.ibm.com/v1/enterprises/$ENTERPRISE_ID/import/accounts/$ACCOUNT_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
  "billing_unit_id": "$BILLING_UNIT_ID"
}'
Copy to clipboard

Example request

importAccountToEnterpriseOptions := enterpriseManagementService.NewImportAccountToEnterpriseOptions(
  enterpriseID,
  importAccountID,
)

response, err := enterpriseManagementService.ImportAccountToEnterprise(importAccountToEnterpriseOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

ImportAccountToEnterpriseOptions importAccountToEnterpriseOptions = new ImportAccountToEnterpriseOptions.Builder()
    .enterpriseId(enterpriseId)
    .accountId(importAccountId)
    .build();

Response<Void> response = enterpriseManagementService.importAccountToEnterprise(importAccountToEnterpriseOptions).execute();

Example request

const params = {
  enterpriseId: enterpriseId,
  accountId: importAccountId,
};

try {
  await enterpriseManagementService.importAccountToEnterprise(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = enterprise_management_service.import_account_to_enterprise(
  enterprise_id=enterprise_id,
  account_id=import_account_id,
)

Response

Status Code

202
The request was accepted and the account was imported into the enterprise. After the account’s billing unit is updated to the enterprise’s, the asynchronous process is complete.
401
Invalid Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Create a new account as a part of an existing enterprise. The API creates an account entity under the parent that is specified in the payload of the request. The request also takes in the name and the owner of this new account. The owner must have a valid IBMid that's registered with IBM Cloud, but they don't need to be a user in the enterprise account.

POST /accounts

(enterpriseManagement *EnterpriseManagementV1) CreateAccount(createAccountOptions *CreateAccountOptions) (result *CreateAccountResponse, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) CreateAccountWithContext(ctx context.Context, createAccountOptions *CreateAccountOptions) (result *CreateAccountResponse, response *core.DetailedResponse, err error)

ServiceCall<CreateAccountResponse> createAccount(CreateAccountOptions createAccountOptions)
Copy to clipboard

createAccount(params)

create_account(self,
        parent: str,
        name: str,
        owner_iam_id: str,
        *,
        traits: 'CreateAccountRequestTraits' = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account.create

Auditing

Calling this method generates the following auditing event.

enterprise.account.create

Request

Instantiate the CreateAccountOptions struct and set the fields to provide parameter values for the CreateAccount method.

Use the CreateAccountOptions.Builder to create a CreateAccountOptions object that contains the parameter values for the createAccount method.

Request Body

Required*

CreateAccountRequest

The body required to create a new account.

parameter

WithContext method only

CreateAccountOptions

The CreateAccount options.

CreateAccountOptions

The createAccount options.

parameters

parent
Required*
string
The CRN of the parent under which the account will be created. The parent can be an existing account group or the enterprise itself.
name
Required*
string
The name of the account. This field must have 3 - 60 characters.
ownerIamId
Required*
string
The IAM ID of the account owner, such as IBMid-0123ABC. The IAM ID must already exist.
traits
The traits object can be used to opt-out of Multi-Factor Authentication setting when creating a child account in the enterprise. This is an optional field.

parameters

parent
Required*
str
The CRN of the parent under which the account will be created. The parent can be an existing account group or the enterprise itself.
name
Required*
str
The name of the account. This field must have 3 - 60 characters.
owner_iam_id
Required*
str
The IAM ID of the account owner, such as IBMid-0123ABC. The IAM ID must already exist.
traits
The traits object can be used to opt-out of Multi-Factor Authentication setting when creating a child account in the enterprise. This is an optional field.

Example request

curl -X POST "https://enterprise.cloud.ibm.com/v1/accounts -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_ID",
  "name": "Example Account",
  "owner_iam_id": "$OWNER_IAM_ID"
}'
Copy to clipboard

Example request to opt-out of Multi-Factor Authentication when creating a child account

Example request to set Enterprise IAM settings when creating a child account

Example request to create IAM service id with IAM api key and owner policies when creating a child account

Example request

createAccountOptions := enterpriseManagementService.NewCreateAccountOptions(
  parentCRN,
  "Example Account",
  enterpriseAccountIamID,
)

createAccountResponse, response, err := enterpriseManagementService.CreateAccount(createAccountOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createAccountResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateAccountOptions createAccountOptions = new CreateAccountOptions.Builder()
    .parent(parentCRN)
    .name("Example Account")
    .ownerIamId(enterpriseAccountIamId)
    .build();

Response<CreateAccountResponse> response = enterpriseManagementService.createAccount(createAccountOptions).execute();
CreateAccountResponse createAccountResponse = response.getResult();

System.out.println(createAccountResponse);

Example request

const params = {
  parent: parentCrn,
  name: 'Example Account',
  ownerIamId: enterpriseAccountIamId,
};

let res;
try {
  res = await enterpriseManagementService.createAccount(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

accountId = res.result.account_id;

params.name = 'New Example Account';

try {
  res = await enterpriseManagementService.createAccount(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

create_account_response = enterprise_management_service.create_account(
  parent=parent_crn,
  name='Example Account',
  owner_iam_id=enterprise_account_iam_id,
).get_result()

print(json.dumps(create_account_response, indent=2))
Copy to clipboard

Response

Response Body

CreateAccountResponse

A newly-created account.

CreateAccountResponse

A newly-created account.

CreateAccountResponse

A newly-created account.

CreateAccountResponse

A newly-created account.

CreateAccountResponse

A newly-created account.

Status Code

202
The create account request completed successfully
400
Bad Request
401
Invalid or Expired Access Token
403
Access Denied
500
Internal Server Error
503
Service Unavailable

Example responses

{ "account_id": "<new-account-id>" }
{ "account_id": "<new-account-id>" }

Status 202

{
  "account_id": "<new-account-id>",
  "iam_service_id": "iam-ServiceId-<service-id-guid>",
  "iam_apikey_id": "ApiKey-<api-key-guid>",
  "iam_apikey": "<actual-api-key>"
}
Copy to clipboard

Success example

{
  "account_id": "<new-account-id>",
  "iam_service_id": "iam-ServiceId-<service-id-guid>",
  "iam_apikey_id": "ApiKey-<api-key-guid>",
  "iam_apikey": "<actual-api-key>"
}
Copy to clipboard

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 500

Error example

Status 503

Error example

Retrieve all accounts based on the values that are passed in the query parameters. If no query parameter is passed, all of the accounts in the enterprise for which the calling identity has access are returned.

You can use pagination parameters to filter the results. The limit field can be used to limit the number of results that are displayed for this method.

This method ensures that only the accounts that the user has access to are returned. Access can be controlled either through a policy on a specific account, or account-level platform services access roles, such as Administrator, Editor, Operator, or Viewer. When you call the method with the enterprise_id, account_group_id or parent query parameter, all of the accounts that are immediate children of this entity are returned. Authentication is performed on all the accounts before they are returned to the user to ensure that only those accounts are returned to which the calling identity has access to.

GET /accounts

(enterpriseManagement *EnterpriseManagementV1) ListAccounts(listAccountsOptions *ListAccountsOptions) (result *ListAccountsResponse, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) ListAccountsWithContext(ctx context.Context, listAccountsOptions *ListAccountsOptions) (result *ListAccountsResponse, response *core.DetailedResponse, err error)

ServiceCall<ListAccountsResponse> listAccounts(ListAccountsOptions listAccountsOptions)
Copy to clipboard

listAccounts(params)

list_accounts(self,
        *,
        enterprise_id: str = None,
        account_group_id: str = None,
        next_docid: str = None,
        parent: str = None,
        limit: int = None,
        include_deleted: bool = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account.retrieve

Request

Instantiate the ListAccountsOptions struct and set the fields to provide parameter values for the ListAccounts method.

Use the ListAccountsOptions.Builder to create a ListAccountsOptions object that contains the parameter values for the listAccounts method.

Query Parameters

enterprise_id
string
Get accounts that are either immediate children or are a part of the hierarchy for a given enterprise ID.
account_group_id
string
Get accounts that are either immediate children or are a part of the hierarchy for a given account group ID.
next_docid
string
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
parent
string
Get accounts that are either immediate children or are a part of the hierarchy for a given parent CRN.
limit
integer
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
Default: 100
include_deleted
boolean
Include the deleted accounts from an enterprise when used in conjunction with enterprise_id.

parameter

WithContext method only

ListAccountsOptions

The ListAccounts options.

ListAccountsOptions

The listAccounts options.

parameters

enterpriseId
string
Get accounts that are either immediate children or are a part of the hierarchy for a given enterprise ID.
accountGroupId
string
Get accounts that are either immediate children or are a part of the hierarchy for a given account group ID.
nextDocid
string
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
parent
string
Get accounts that are either immediate children or are a part of the hierarchy for a given parent CRN.
limit
number
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
includeDeleted
boolean
Include the deleted accounts from an enterprise when used in conjunction with enterprise_id.

parameters

enterprise_id
str
Get accounts that are either immediate children or are a part of the hierarchy for a given enterprise ID.
account_group_id
str
Get accounts that are either immediate children or are a part of the hierarchy for a given account group ID.
next_docid
str
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
parent
str
Get accounts that are either immediate children or are a part of the hierarchy for a given parent CRN.
limit
int
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
include_deleted
bool
Include the deleted accounts from an enterprise when used in conjunction with enterprise_id.

Example request

curl -X GET "https://enterprise.cloud.ibm.com/v1/accounts?enterprise_id=$ENTERPRISE_ID&limit=100&include_deleted=true" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

listAccountsOptions := &enterprisemanagementv1.ListAccountsOptions{
  EnterpriseID: &enterpriseID,
}

pager, err := enterpriseManagementService.NewAccountsPager(listAccountsOptions)
if err != nil {
  panic(err)
}

var allResults []enterprisemanagementv1.Account
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListAccountsOptions listAccountsOptions = new ListAccountsOptions.Builder()
  .enterpriseId(enterpriseId)
  .build();

AccountsPager pager = new AccountsPager(enterpriseManagementService, listAccountsOptions);
List<Account> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<Account> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  enterpriseId: enterpriseId,
};

const allResults = [];
try {
  const pager = new EnterpriseManagementV1.AccountsPager(enterpriseManagementService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = AccountsPager(
  client=enterprise_management_service,
  enterprise_id=enterprise_id,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

ListAccountsResponse

The list_accounts operation response.

ListAccountsResponse

The list_accounts operation response.

ListAccountsResponse

The list_accounts operation response.

ListAccountsResponse

The list_accounts operation response.

ListAccountsResponse

The list_accounts operation response.

Status Code

200
Success
401
Invalid or Expired Access Token
403
Access Denied
500
Internal Server Error
503
Service Unavailable

Example responses

Status 200

{
  "rows_count": 2,
  "next_url": "/v1/accounts?$ACCOUNT_1_ID&next_docid=$NEXT_DOCID",
  "resources": [
    {
      "url": "/v1/accounts/$ACCOUNT_1_ID",
      "id": "$ACCOUNT_1_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1/account-group:$ACCOUNT_GROUP_2",
      "name": "IBM",
      "state": "ACTIVE",
      "paid": true,
      "owner_iam_id": "IBMid-55MNOP",
      "owner_email": "user@example.com",
      "created_at": "2019-05-14T19:45:01.071Z",
      "updated_at": "2019-05-14T19:46:53.695Z",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account:$ACCOUNT_1_ID",
      "is_enterprise_account": false,
      "created_by": "iam-ServiceId-acab",
      "updated_by": "iam-ServiceId-acab"
    },
    {
      "url": "/v1/accounts/$ENTERPRISE_ACCOUNT_ID",
      "id": "$ENTERPRISE_ACCOUNT_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID",
      "name": "Billing Fields Enterprise 5",
      "state": "ACTIVE",
      "paid": true,
      "owner_iam_id": "IBMid-55HIJK",
      "owner_email": "user@example.com",
      "created_at": "2019-05-14T19:46:53.495Z",
      "updated_at": "2019-05-19T21:14:15.079Z",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account:$ENTERPRISE_ACCOUNT_ID",
      "is_enterprise_account": true,
      "created_by": "iam-ServiceId-acab",
      "updated_by": "iam-ServiceId-acab"
    }
  ]
}
Copy to clipboard

Success example

{
  "rows_count": 2,
  "next_url": "/v1/accounts?$ACCOUNT_1_ID&next_docid=$NEXT_DOCID",
  "resources": [
    {
      "url": "/v1/accounts/$ACCOUNT_1_ID",
      "id": "$ACCOUNT_1_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1/account-group:$ACCOUNT_GROUP_2",
      "name": "IBM",
      "state": "ACTIVE",
      "paid": true,
      "owner_iam_id": "IBMid-55MNOP",
      "owner_email": "user@example.com",
      "created_at": "2019-05-14T19:45:01.071Z",
      "updated_at": "2019-05-14T19:46:53.695Z",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account:$ACCOUNT_1_ID",
      "is_enterprise_account": false,
      "created_by": "iam-ServiceId-acab",
      "updated_by": "iam-ServiceId-acab"
    },
    {
      "url": "/v1/accounts/$ENTERPRISE_ACCOUNT_ID",
      "id": "$ENTERPRISE_ACCOUNT_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID",
      "name": "Billing Fields Enterprise 5",
      "state": "ACTIVE",
      "paid": true,
      "owner_iam_id": "IBMid-55HIJK",
      "owner_email": "user@example.com",
      "created_at": "2019-05-14T19:46:53.495Z",
      "updated_at": "2019-05-19T21:14:15.079Z",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account:$ENTERPRISE_ACCOUNT_ID",
      "is_enterprise_account": true,
      "created_by": "iam-ServiceId-acab",
      "updated_by": "iam-ServiceId-acab"
    }
  ]
}
Copy to clipboard

Status 401

Error example

Status 403

Error example

Status 500

Error example

Status 503

Error example

Retrieve an account by the account_id parameter. All data related to the account is returned only if the caller has access to retrieve the account.

GET /accounts/{account_id}

(enterpriseManagement *EnterpriseManagementV1) GetAccount(getAccountOptions *GetAccountOptions) (result *Account, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) GetAccountWithContext(ctx context.Context, getAccountOptions *GetAccountOptions) (result *Account, response *core.DetailedResponse, err error)

ServiceCall<Account> getAccount(GetAccountOptions getAccountOptions)
Copy to clipboard

getAccount(params)

get_account(self,
        account_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account.retrieve

Request

Instantiate the GetAccountOptions struct and set the fields to provide parameter values for the GetAccount method.

Use the GetAccountOptions.Builder to create a GetAccountOptions object that contains the parameter values for the getAccount method.

Path Parameters

account_id
Required*
string
The ID of the target account.

parameter

WithContext method only

GetAccountOptions

The GetAccount options.

GetAccountOptions

The getAccount options.

parameters

accountId
Required*
string
The ID of the target account.

parameters

account_id
Required*
str
The ID of the target account.

Example request

curl -X GET "https://enterprise.cloud.ibm.com/v1/accounts/$ACCOUNT_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

getAccountOptions := enterpriseManagementService.NewGetAccountOptions(
  accountID,
)

account, response, err := enterpriseManagementService.GetAccount(getAccountOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(account, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetAccountOptions getAccountOptions = new GetAccountOptions.Builder()
    .accountId(accountId)
    .build();

Response<Account> response = enterpriseManagementService.getAccount(getAccountOptions).execute();
Account account = response.getResult();

System.out.println(account);

Example request

const params = {
  accountId: accountId,
};

try {
  const res = await enterpriseManagementService.getAccount(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

account = enterprise_management_service.get_account(
  account_id=account_id,
).get_result()

print(json.dumps(account, indent=2))

Response

Response Body

Account

An account resource

Account

An account resource.

Account

An account resource.

Account

An account resource.

Account

An account resource.

Status Code

200
Successfully retrieved account by ID
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 200

{
  "url": "/v1/accounts/$ACCOUNT_1_ID",
  "id": "$ACCOUNT_1_ID",
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
  "enterprise_id": "$ENTERPRISE_ID",
  "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1/account-group:$ACCOUNT_GROUP_2",
  "name": "IBM",
  "state": "ACTIVE",
  "paid": true,
  "owner_iam_id": "IBMid-55MNOP",
  "owner_email": "user@example.com",
  "created_at": "2019-05-14T19:45:01.071Z",
  "updated_at": "2019-05-14T19:46:53.695Z",
  "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account:$ACCOUNT_1_ID",
  "is_enterprise_account": false,
  "created_by": "iam-ServiceId-acab",
  "updated_by": "iam-ServiceId-acab"
}
Copy to clipboard

Success example

{
  "url": "/v1/accounts/$ACCOUNT_1_ID",
  "id": "$ACCOUNT_1_ID",
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
  "enterprise_id": "$ENTERPRISE_ID",
  "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1/account-group:$ACCOUNT_GROUP_2",
  "name": "IBM",
  "state": "ACTIVE",
  "paid": true,
  "owner_iam_id": "IBMid-55MNOP",
  "owner_email": "user@example.com",
  "created_at": "2019-05-14T19:45:01.071Z",
  "updated_at": "2019-05-14T19:46:53.695Z",
  "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account:$ACCOUNT_1_ID",
  "is_enterprise_account": false,
  "created_by": "iam-ServiceId-acab",
  "updated_by": "iam-ServiceId-acab"
}
Copy to clipboard

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Move an account to a different parent within the same enterprise.

PATCH /accounts/{account_id}

(enterpriseManagement *EnterpriseManagementV1) UpdateAccount(updateAccountOptions *UpdateAccountOptions) (response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) UpdateAccountWithContext(ctx context.Context, updateAccountOptions *UpdateAccountOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> updateAccount(UpdateAccountOptions updateAccountOptions)
Copy to clipboard

updateAccount(params)

update_account(self,
        account_id: str,
        parent: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account.move

Auditing

Calling this method generates the following auditing event.

enterprise.account.move

Request

Instantiate the UpdateAccountOptions struct and set the fields to provide parameter values for the UpdateAccount method.

Use the UpdateAccountOptions.Builder to create a UpdateAccountOptions object that contains the parameter values for the updateAccount method.

Path Parameters

account_id
Required*
string
The ID of the target account.

Request Body

Required*

MoveAccountRequest

The ID of the account to move.

parameter

WithContext method only

UpdateAccountOptions

The UpdateAccount options.

UpdateAccountOptions

The updateAccount options.

parameters

accountId
Required*
string
The ID of the target account.
parent
Required*
string
The CRN of the new parent within the enterprise.

parameters

account_id
Required*
str
The ID of the target account.
parent
Required*
str
The CRN of the new parent within the enterprise.

Example request

curl -X PATCH "https://enterprise.cloud.ibm.com/v1/accounts/$ACCOUNT_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "parent": crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$NEW_PARENT_ACCOUNT_GROUP"",
}'
Copy to clipboard

Example request

updateAccountOptions := enterpriseManagementService.NewUpdateAccountOptions(
  accountID,
  newParentCRN,
)

response, err := enterpriseManagementService.UpdateAccount(updateAccountOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UpdateAccountOptions updateAccountOptions = new UpdateAccountOptions.Builder()
    .accountId(accountId)
    .parent(newParentCRN)
    .build();

Response<Void> response = enterpriseManagementService.updateAccount(updateAccountOptions).execute();

Example request

const params = {
  accountId: newAccountId,
  parent: newParentCrn,
};

try {
  await enterpriseManagementService.updateAccount(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = enterprise_management_service.update_account(
  account_id=account_id,
  parent=new_parent_crn,
)

Response

Status Code

202
Moving account process is in PENDING state. After the parent field of the account shows the new parent, asynchronous processing is complete.
204
Update Successful
400
Bad Request. The payload passed to the request is invalid.
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Remove an account from the enterprise its currently in. After an account is removed, it will be canceled and cannot be reactivated.

DELETE /accounts/{account_id}

(enterpriseManagement *EnterpriseManagementV1) DeleteAccount(deleteAccountOptions *DeleteAccountOptions) (response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) DeleteAccountWithContext(ctx context.Context, deleteAccountOptions *DeleteAccountOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteAccount(DeleteAccountOptions deleteAccountOptions)
Copy to clipboard

deleteAccount(params)

delete_account(self,
        account_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account.delete

Auditing

Calling this method generates the following auditing event.

enterprise.account.delete

Request

Instantiate the DeleteAccountOptions struct and set the fields to provide parameter values for the DeleteAccount method.

Use the DeleteAccountOptions.Builder to create a DeleteAccountOptions object that contains the parameter values for the deleteAccount method.

Path Parameters

account_id
Required*
string
The ID of the target account.

parameter

WithContext method only

DeleteAccountOptions

The DeleteAccount options.

DeleteAccountOptions

The deleteAccount options.

parameters

accountId
Required*
string
The ID of the target account.

parameters

account_id
Required*
str
The ID of the target account.

Example request

curl -X DELETE "https://enterprise.cloud.ibm.com/v1/accounts/$ACCOUNT_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

deleteAccountOptions := enterpriseManagementService.NewDeleteAccountOptions(
  accountID,
)

response, err := enterpriseManagementService.DeleteAccount(deleteAccountOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteAccountOptions deleteAccountOptions = new DeleteAccountOptions.Builder()
  .accountId(accountId)
  .build();

Response<Void> response = enterpriseManagementService.deleteAccount(deleteAccountOptions).execute();

Example request

const params = {
  accountId,
};

try {
  await enterpriseManagementService.deleteAccount(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = enterprise_management_service.delete_account(
  account_id=account_id,
)

Response

Status Code

204
Successfully removed the account from the enterprise.
400
Bad Request
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Create a new account group, which can be used to group together multiple accounts. To create an account group, you must have an existing enterprise. The API creates an account group entity under the parent that is specified in the payload of the request. The request also takes in the name and the primary contact of this new account group.

POST /account-groups

(enterpriseManagement *EnterpriseManagementV1) CreateAccountGroup(createAccountGroupOptions *CreateAccountGroupOptions) (result *CreateAccountGroupResponse, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) CreateAccountGroupWithContext(ctx context.Context, createAccountGroupOptions *CreateAccountGroupOptions) (result *CreateAccountGroupResponse, response *core.DetailedResponse, err error)

ServiceCall<CreateAccountGroupResponse> createAccountGroup(CreateAccountGroupOptions createAccountGroupOptions)
Copy to clipboard

createAccountGroup(params)

create_account_group(self,
        parent: str,
        name: str,
        primary_contact_iam_id: str,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account-group.create

Auditing

Calling this method generates the following auditing event.

enterprise.account-group.create

Request

Instantiate the CreateAccountGroupOptions struct and set the fields to provide parameter values for the CreateAccountGroup method.

Use the CreateAccountGroupOptions.Builder to create a CreateAccountGroupOptions object that contains the parameter values for the createAccountGroup method.

Request Body

Required*

CreateAccountGroupRequest

The body that is required to create an account group.

parameter

WithContext method only

CreateAccountGroupOptions

The CreateAccountGroup options.

CreateAccountGroupOptions

The createAccountGroup options.

parameters

parent
Required*
string
The CRN of the parent under which the account group will be created. The parent can be an existing account group or the enterprise itself.
name
Required*
string
The name of the account group. This field must have 3 - 60 characters.
primaryContactIamId
Required*
string
The IAM ID of the primary contact for this account group, such as IBMid-0123ABC. The IAM ID must already exist.

parameters

parent
Required*
str
The CRN of the parent under which the account group will be created. The parent can be an existing account group or the enterprise itself.
name
Required*
str
The name of the account group. This field must have 3 - 60 characters.
primary_contact_iam_id
Required*
str
The IAM ID of the primary contact for this account group, such as IBMid-0123ABC. The IAM ID must already exist.

Example request

curl -X POST "https://enterprise.cloud.ibm.com/v1/account-groups -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
  "name": "Example Account Group",
  "primary_contact_iam_id": "$PRIMARY_CONTACT_IAM_ID"
}'
Copy to clipboard

Example request

createAccountGroupOptions := enterpriseManagementService.NewCreateAccountGroupOptions(
  parentCRN,
  "Example Account Group",
  enterpriseAccountIamID,
)

createAccountGroupResponse, response, err := enterpriseManagementService.CreateAccountGroup(createAccountGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createAccountGroupResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateAccountGroupOptions createAccountGroupOptions = new CreateAccountGroupOptions.Builder()
    .parent(parentCRN)
    .name("Example Account Group")
    .primaryContactIamId(enterpriseAccountIamId)
    .build();

Response<CreateAccountGroupResponse> response = enterpriseManagementService.createAccountGroup(createAccountGroupOptions).execute();
CreateAccountGroupResponse createAccountGroupResponse = response.getResult();

System.out.println(createAccountGroupResponse);

Example request

const params = {
  parent: parentCrn,
  name: 'Example Account Group',
  primaryContactIamId: enterpriseAccountIamId,
};

let res;
try {
  res = await enterpriseManagementService.createAccountGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

accountGroupId = res.result.account_group_id;

params.name = 'New Example Account Group';

try {
  res = await enterpriseManagementService.createAccountGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

create_account_group_response = enterprise_management_service.create_account_group(
  parent=parent_crn,
  name='Example Account Group',
  primary_contact_iam_id=enterprise_account_iam_id,
).get_result()

print(json.dumps(create_account_group_response, indent=2))
Copy to clipboard

Response

Response Body

CreateAccountGroupResponse

A newly-created account group.

CreateAccountGroupResponse

A newly-created account group.

CreateAccountGroupResponse

A newly-created account group.

CreateAccountGroupResponse

A newly-created account group.

CreateAccountGroupResponse

A newly-created account group.

Status Code

201
Create account group request completed successfully.
400
Bad Request
401
Invalid or Expired Access Token
403
Access Denied
500
Internal Server Error
503
Service Unavailable

Example responses

Status 201

{
  "account_group_id": "$ACCOUNT_GROUP_ID"
}

Success example

{
  "account_group_id": "$ACCOUNT_GROUP_ID"
}

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 500

Error example

Status 503

Error example

Retrieve all account groups based on the values that are passed in the query parameters. If no query parameter is passed, all of the account groups in the enterprise for which the calling identity has access are returned.

You can use pagination parameters to filter the results. The limit field can be used to limit the number of results that are displayed for this method.

This method ensures that only the account groups that the user has access to are returned. Access can be controlled either through a policy on a specific account group, or account-level platform services access roles, such as Administrator, Editor, Operator, or Viewer. When you call the method with the enterprise_id, parent_account_group_id or parent query parameter, all of the account groups that are immediate children of this entity are returned. Authentication is performed on all account groups before they are returned to the user to ensure that only those account groups are returned to which the calling identity has access.

GET /account-groups

(enterpriseManagement *EnterpriseManagementV1) ListAccountGroups(listAccountGroupsOptions *ListAccountGroupsOptions) (result *ListAccountGroupsResponse, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) ListAccountGroupsWithContext(ctx context.Context, listAccountGroupsOptions *ListAccountGroupsOptions) (result *ListAccountGroupsResponse, response *core.DetailedResponse, err error)

ServiceCall<ListAccountGroupsResponse> listAccountGroups(ListAccountGroupsOptions listAccountGroupsOptions)
Copy to clipboard

listAccountGroups(params)

list_account_groups(self,
        *,
        enterprise_id: str = None,
        parent_account_group_id: str = None,
        next_docid: str = None,
        parent: str = None,
        limit: int = None,
        include_deleted: bool = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account-group.retrieve

Request

Instantiate the ListAccountGroupsOptions struct and set the fields to provide parameter values for the ListAccountGroups method.

Use the ListAccountGroupsOptions.Builder to create a ListAccountGroupsOptions object that contains the parameter values for the listAccountGroups method.

Query Parameters

enterprise_id
string
Get account groups that are either immediate children or are a part of the hierarchy for a given enterprise ID.
parent_account_group_id
string
Get account groups that are either immediate children or are a part of the hierarchy for a given account group ID.
next_docid
string
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
parent
string
Get account groups that are either immediate children or are a part of the hierarchy for a given parent CRN.
limit
integer
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
Default: 100
include_deleted
boolean
Include the deleted account groups from an enterprise when used in conjunction with other query parameters.

parameter

WithContext method only

ListAccountGroupsOptions

The ListAccountGroups options.

ListAccountGroupsOptions

The listAccountGroups options.

parameters

enterpriseId
string
Get account groups that are either immediate children or are a part of the hierarchy for a given enterprise ID.
parentAccountGroupId
string
Get account groups that are either immediate children or are a part of the hierarchy for a given account group ID.
nextDocid
string
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
parent
string
Get account groups that are either immediate children or are a part of the hierarchy for a given parent CRN.
limit
number
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
includeDeleted
boolean
Include the deleted account groups from an enterprise when used in conjunction with other query parameters.

parameters

enterprise_id
str
Get account groups that are either immediate children or are a part of the hierarchy for a given enterprise ID.
parent_account_group_id
str
Get account groups that are either immediate children or are a part of the hierarchy for a given account group ID.
next_docid
str
The first item to be returned in the page of results. This value can be obtained from the next_url property from the previous call of the operation. If not specified, then the first page of results is returned.
parent
str
Get account groups that are either immediate children or are a part of the hierarchy for a given parent CRN.
limit
int
Return results up to this limit. Valid values are between 0 and 100.

Possible values: value ≤ 100
include_deleted
bool
Include the deleted account groups from an enterprise when used in conjunction with other query parameters.

Example request

curl -X GET "https://enterprise.cloud.ibm.com/v1/account-groups?enterprise_id=$ENTERPRISE_ID&limit=100&include_deleted=true" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

listAccountGroupsOptions := &enterprisemanagementv1.ListAccountGroupsOptions{
  EnterpriseID: &enterpriseID,
}

pager, err := enterpriseManagementService.NewAccountGroupsPager(listAccountGroupsOptions)
if err != nil {
  panic(err)
}

var allResults []enterprisemanagementv1.AccountGroup
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListAccountGroupsOptions listAccountGroupsOptions = new ListAccountGroupsOptions.Builder()
  .enterpriseId(enterpriseId)
  .build();

AccountGroupsPager pager = new AccountGroupsPager(enterpriseManagementService, listAccountGroupsOptions);
List<AccountGroup> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<AccountGroup> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  enterpriseId: enterpriseId,
};

const allResults = [];
try {
  const pager = new EnterpriseManagementV1.AccountGroupsPager(enterpriseManagementService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = AccountGroupsPager(
  client=enterprise_management_service,
  enterprise_id=enterprise_id,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

ListAccountGroupsResponse

The list_account_groups operation response

ListAccountGroupsResponse

The list_account_groups operation response.

ListAccountGroupsResponse

The list_account_groups operation response.

ListAccountGroupsResponse

The list_account_groups operation response.

ListAccountGroupsResponse

The list_account_groups operation response.

Status Code

200
Success
401
Invalid or Expired Access Token
403
Access Denied
500
Internal Server Error
503
Service Unavailable

Example responses

Status 200

{
  "rows_count": 2,
  "next_url": "/v1/account-groups?$ACCOUNT_GROUP_1_ID&next_docid=$NEXT_DOCID",
  "resources": [
    {
      "url": "/v1/account-groups/$ACCOUNT_GROUP_1_ID",
      "id": "$ACCOUNT_GROUP_1_ID",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_1_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID",
      "name": "Updated Account Group History Name",
      "state": "ACTIVE",
      "primary_contact_iam_id": "IBMid-55ABCD",
      "primary_contact_email": "user@example.com",
      "created_at": "2019-07-02T08:46:01.582Z",
      "updated_at": "2019-07-02T08:47:49.285Z",
      "created_by": "iam-ServiceId-acab",
      "updated_by": "iam-ServiceId-acab"
    },
    {
      "url": "/v1/account-groups/$ACCOUNT_GROUP_2_ID",
      "id": "$ACCOUNT_GROUP_2_ID",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_1_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1_ID",
      "name": "Example Account Group",
      "state": "ACTIVE",
      "primary_contact_iam_id": "IBMid-55EFGH",
      "primary_contact_email": "user@example.com",
      "created_at": "2019-05-16T18:05:56.659Z",
      "updated_at": "2019-05-16T18:05:56.659Z",
      "created_by": "iam-ServiceId-c8da",
      "updated_by": "iam-ServiceId-c8da"
    }
  ]
}
Copy to clipboard

Success example

{
  "rows_count": 2,
  "next_url": "/v1/account-groups?$ACCOUNT_GROUP_1_ID&next_docid=$NEXT_DOCID",
  "resources": [
    {
      "url": "/v1/account-groups/$ACCOUNT_GROUP_1_ID",
      "id": "$ACCOUNT_GROUP_1_ID",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_1_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::enterprise:$ENTERPRISE_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID",
      "name": "Updated Account Group History Name",
      "state": "ACTIVE",
      "primary_contact_iam_id": "IBMid-55ABCD",
      "primary_contact_email": "user@example.com",
      "created_at": "2019-07-02T08:46:01.582Z",
      "updated_at": "2019-07-02T08:47:49.285Z",
      "created_by": "iam-ServiceId-acab",
      "updated_by": "iam-ServiceId-acab"
    },
    {
      "url": "/v1/account-groups/$ACCOUNT_GROUP_2_ID",
      "id": "$ACCOUNT_GROUP_2_ID",
      "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2_ID",
      "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_1_ID",
      "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
      "enterprise_id": "$ENTERPRISE_ID",
      "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1_ID",
      "name": "Example Account Group",
      "state": "ACTIVE",
      "primary_contact_iam_id": "IBMid-55EFGH",
      "primary_contact_email": "user@example.com",
      "created_at": "2019-05-16T18:05:56.659Z",
      "updated_at": "2019-05-16T18:05:56.659Z",
      "created_by": "iam-ServiceId-c8da",
      "updated_by": "iam-ServiceId-c8da"
    }
  ]
}
Copy to clipboard

Status 401

Error example

Status 403

Error example

Status 500

Error example

Status 503

Error example

Retrieve an account by the account_group_id parameter. All data related to the account group is returned only if the caller has access to retrieve the account group.

GET /account-groups/{account_group_id}

(enterpriseManagement *EnterpriseManagementV1) GetAccountGroup(getAccountGroupOptions *GetAccountGroupOptions) (result *AccountGroup, response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) GetAccountGroupWithContext(ctx context.Context, getAccountGroupOptions *GetAccountGroupOptions) (result *AccountGroup, response *core.DetailedResponse, err error)

ServiceCall<AccountGroup> getAccountGroup(GetAccountGroupOptions getAccountGroupOptions)
Copy to clipboard

getAccountGroup(params)

get_account_group(self,
        account_group_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account-group.retrieve

Request

Instantiate the GetAccountGroupOptions struct and set the fields to provide parameter values for the GetAccountGroup method.

Use the GetAccountGroupOptions.Builder to create a GetAccountGroupOptions object that contains the parameter values for the getAccountGroup method.

Path Parameters

account_group_id
Required*
string
The ID of the account group to retrieve.

parameter

WithContext method only

GetAccountGroupOptions

The GetAccountGroup options.

GetAccountGroupOptions

The getAccountGroup options.

parameters

accountGroupId
Required*
string
The ID of the account group to retrieve.

parameters

account_group_id
Required*
str
The ID of the account group to retrieve.

Example request

curl -X GET "https://enterprise.cloud.ibm.com/v1/account-groups/$ACCOUNT_GROUP_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

getAccountGroupOptions := enterpriseManagementService.NewGetAccountGroupOptions(
  accountGroupID,
)

accountGroup, response, err := enterpriseManagementService.GetAccountGroup(getAccountGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(accountGroup, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetAccountGroupOptions getAccountGroupOptions = new GetAccountGroupOptions.Builder()
    .accountGroupId(accountGroupId)
    .build();

Response<AccountGroup> response = enterpriseManagementService.getAccountGroup(getAccountGroupOptions).execute();
AccountGroup accountGroup = response.getResult();

System.out.println(accountGroup);

Example request

const params = {
  accountGroupId: accountGroupId,
};

try {
  const res = await enterpriseManagementService.getAccountGroup(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

account_group = enterprise_management_service.get_account_group(
  account_group_id=account_group_id,
).get_result()

print(json.dumps(account_group, indent=2))

Response

Response Body

AccountGroup

An account group resource

AccountGroup

An account group resource.

AccountGroup

An account group resource.

AccountGroup

An account group resource.

AccountGroup

An account group resource.

Status Code

200
Successfully retrieved account group by ID.
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 200

{
  "url": "/v1/account-groups/$ACCOUNT_GROUP_2_ID",
  "id": "$ACCOUNT_GROUP_2_ID",
  "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2_ID",
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_1_ID",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
  "enterprise_id": "$ENTERPRISE_ID",
  "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1_ID",
  "name": "Example Account Group",
  "state": "ACTIVE",
  "primary_contact_iam_id": "IBMid-55EFGH",
  "primary_contact_email": "user@example.com",
  "created_at": "2019-05-16T18:05:56.659Z",
  "updated_at": "2019-05-16T18:05:56.659Z",
  "created_by": "iam-ServiceId-c8da",
  "updated_by": "iam-ServiceId-c8da"
}
Copy to clipboard

Success example

{
  "url": "/v1/account-groups/$ACCOUNT_GROUP_2_ID",
  "id": "$ACCOUNT_GROUP_2_ID",
  "crn": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_2_ID",
  "parent": "crn:v1:bluemix:public:enterprise::a/$ENTERPRISE_ACCOUNT_ID::account-group:$ACCOUNT_GROUP_1_ID",
  "enterprise_account_id": "$ENTERPRISE_ACCOUNT_ID",
  "enterprise_id": "$ENTERPRISE_ID",
  "enterprise_path": "enterprise:$ENTERPRISE_ID/account-group:$ACCOUNT_GROUP_1_ID",
  "name": "Example Account Group",
  "state": "ACTIVE",
  "primary_contact_iam_id": "IBMid-55EFGH",
  "primary_contact_email": "user@example.com",
  "created_at": "2019-05-16T18:05:56.659Z",
  "updated_at": "2019-05-16T18:05:56.659Z",
  "created_by": "iam-ServiceId-c8da",
  "updated_by": "iam-ServiceId-c8da"
}
Copy to clipboard

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Update the name or IAM ID of the primary contact for an existing account group. The new primary contact must already be a user in the enterprise account.

PATCH /account-groups/{account_group_id}

(enterpriseManagement *EnterpriseManagementV1) UpdateAccountGroup(updateAccountGroupOptions *UpdateAccountGroupOptions) (response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) UpdateAccountGroupWithContext(ctx context.Context, updateAccountGroupOptions *UpdateAccountGroupOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> updateAccountGroup(UpdateAccountGroupOptions updateAccountGroupOptions)
Copy to clipboard

updateAccountGroup(params)

update_account_group(self,
        account_group_id: str,
        *,
        name: str = None,
        primary_contact_iam_id: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account-group.update

Auditing

Calling this method generates the following auditing event.

enterprise.account-group.update

Request

Instantiate the UpdateAccountGroupOptions struct and set the fields to provide parameter values for the UpdateAccountGroup method.

Use the UpdateAccountGroupOptions.Builder to create a UpdateAccountGroupOptions object that contains the parameter values for the updateAccountGroup method.

Path Parameters

account_group_id
Required*
string
The ID of the account group to retrieve.

Request Body

Required*

UpdateAccountGroupRequest

The ID of the account group to update.

parameter

WithContext method only

UpdateAccountGroupOptions

The UpdateAccountGroup options.

UpdateAccountGroupOptions

The updateAccountGroup options.

parameters

accountGroupId
Required*
string
The ID of the account group to retrieve.
name
string
The new name of the account group. This field must have 3 - 60 characters.
primaryContactIamId
string
The IAM ID of the user to be the new primary contact for the account group.

parameters

account_group_id
Required*
str
The ID of the account group to retrieve.
name
str
The new name of the account group. This field must have 3 - 60 characters.
primary_contact_iam_id
str
The IAM ID of the user to be the new primary contact for the account group.

Example request

curl -X PATCH "https://enterprise.cloud.ibm.com/v1/account-groups/$ACCOUNT_GROUP_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json' -d '{
  "name": "Updated Example Account Group",
}'
Copy to clipboard

Example request

updateAccountGroupOptions := enterpriseManagementService.NewUpdateAccountGroupOptions(
  accountGroupID,
)
updateAccountGroupOptions.SetName("Updated Example Account Group")
updateAccountGroupOptions.SetPrimaryContactIamID(enterpriseAccountIamID)

response, err := enterpriseManagementService.UpdateAccountGroup(updateAccountGroupOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UpdateAccountGroupOptions updateAccountGroupOptions = new UpdateAccountGroupOptions.Builder()
    .accountGroupId(accountGroupId)
    .name("Updated Example Account Group")
    .build();

Response<Void> response = enterpriseManagementService.updateAccountGroup(updateAccountGroupOptions).execute();

Example request

const params = {
  accountGroupId: accountGroupId,
  name: 'Updated Example Account Group',
  primaryContactIamId: enterpriseAccountIamId,
};

try {
  await enterpriseManagementService.updateAccountGroup(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = enterprise_management_service.update_account_group(
  account_group_id=account_group_id,
  name='Updated Example Account Group',
  primary_contact_iam_id=enterprise_account_iam_id,
)

Response

Status Code

204
Success
400
Bad Request. The payload passed to the request is invalid.
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Delete an existing account group from the enterprise. You can't delete an account group that has child account groups, the delete request will fail. This API doesn't perform a recursive delete on the child account groups, it only deletes the current account group.

DELETE /account-groups/{account_group_id}

(enterpriseManagement *EnterpriseManagementV1) DeleteAccountGroup(deleteAccountGroupOptions *DeleteAccountGroupOptions) (response *core.DetailedResponse, err error)

(enterpriseManagement *EnterpriseManagementV1) DeleteAccountGroupWithContext(ctx context.Context, deleteAccountGroupOptions *DeleteAccountGroupOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteAccountGroup(DeleteAccountGroupOptions deleteAccountGroupOptions)
Copy to clipboard

deleteAccountGroup(params)

delete_account_group(self,
        account_group_id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

enterprise.account-group.delete

Auditing

Calling this method generates the following auditing event.

enterprise.account-group.delete

Request

Instantiate the DeleteAccountGroupOptions struct and set the fields to provide parameter values for the DeleteAccountGroup method.

Use the DeleteAccountGroupOptions.Builder to create a DeleteAccountGroupOptions object that contains the parameter values for the deleteAccountGroup method.

Path Parameters

account_group_id
Required*
string
The ID of the account group to retrieve.

parameter

WithContext method only

DeleteAccountGroupOptions

The DeleteAccountGroup options.

DeleteAccountGroupOptions

The deleteAccountGroup options.

parameters

accountGroupId
Required*
string
The ID of the account group to retrieve.

parameters

account_group_id
Required*
str
The ID of the account group to retrieve.

Example request

curl -X DELETE "https://enterprise.cloud.ibm.com/v1/account-groups/$ACCOUNT_GROUP_ID" -H "Authorization: Bearer <IAM_Token>" -H 'Content-Type: application/json'
Copy to clipboard

Example request

deleteAccountGroupOptions := enterpriseManagementService.NewDeleteAccountGroupOptions(
  accountGroupID,
)

response, err := enterpriseManagementService.DeleteAccountGroup(deleteAccountGroupOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteAccountGroupOptions deleteAccountGroupOptions = new DeleteAccountGroupOptions.Builder()
  .accountGroupId(accountGroupId)
  .build();

Response<Void> response = enterpriseManagementService.deleteAccountGroup(deleteAccountGroupOptions).execute();

Example request

const params = {
  accountGroupId,
};

try {
  await enterpriseManagementService.deleteAccountGroup(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = enterprise_management_service.delete_account_group(
  account_group_id=account_group_id,
)

Response

Status Code

204
Successfully removed the account group from the enterprise.
400
Bad Request.
401
Invalid or Expired Access Token
403
Access Denied
404
Not Found
500
Internal Server Error
503
Service Unavailable

Example responses

Status 400

Error example

Status 401

Error example

Status 403

Error example

Status 404

Error example

Status 500

Error example

Status 503

Error example

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Pagination

Rate limiting

Related APIs

Methods

Create an enterprise

Authorization

Auditing

Request

Request Body

source_account_id

name

primary_contact_iam_id

domain

parameter

ctx

CreateEnterpriseOptions

SourceAccountID

Name

PrimaryContactIamID

Domain

CreateEnterpriseOptions

sourceAccountId

name

primaryContactIamId

domain

parameters

sourceAccountId

name

primaryContactIamId

domain

parameters

source_account_id

name

primary_contact_iam_id

domain

Response

Response Body

enterprise_id

enterprise_account_id

CreateEnterpriseResponse

EnterpriseID

EnterpriseAccountID

CreateEnterpriseResponse

enterpriseId

enterpriseAccountId

CreateEnterpriseResponse

enterprise_id

enterprise_account_id

CreateEnterpriseResponse

enterprise_id

enterprise_account_id

Status Code

202

400

401

403

500

503

List enterprises

Authorization

Request

Query Parameters

enterprise_account_id

account_group_id

account_id

next_docid

limit

parameter

ctx

ListEnterprisesOptions

EnterpriseAccountID

AccountGroupID

AccountID

NextDocid

Limit