Introduction

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>

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 access for enterprise management.

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}'

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();

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

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({});

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 Logs service. Whenever an API method is called, an event is generated that you can then track and audit from within IBM Cloud Logs. The specific event type is listed for each individual method.

For more information about how to track activity in an enterprise, see Activity tracking events for enterprise 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 many 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.

By default, each page contains 100 items, which is also the maximum number of items per page. To specify a different number of items per page, 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.

Related APIs

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.
Resource Controller API: Manage resource instances, keys, bindings, and more.

Enterprise Management API | IBM Cloud API Docs