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.

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.

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

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?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?parent_account_group_id={account_group_id}
  • /v1/account-groups?parent={parent_crn}
  • /v1/accounts
  • /v1/accounts?enterprise_id={enterprise_id}
  • /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:

Methods

Create an enterprise

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
Request

The body required to create an enterprise.

Response

Status Code

  • Create Enterprise request accepted

  • Bad Request

  • Invalid or Expired Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses

Get enterprise by query parameter

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
Request

Query Parameters

  • Get enterprises for a given enterprise account ID.

  • Get enterprises for a given account group ID.

  • Get enterprises for a given account ID.

  • Return results up to this limit. Valid values are between 0 and 100.

    Default: 100

Response

Status Code

  • Success

  • Invalid or Expired Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses

Get enterprise by ID

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

Path Parameters

  • The ID of the enterprise to retrieve.

Response

Status Code

  • Successfully retrieved enterprise by ID

  • Invalid or Expired Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses

Update an enterprise

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

Path Parameters

  • The ID of the enterprise to update.

Parameters to update the enterprise.

Response

Status Code

  • Success

  • Bad Request. The payload passed to the request is invalid.

  • Invalid or Expired Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses

Import an account into an enterprise

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

Path Parameters

  • The ID of the enterprise to import the stand-alone account into.

  • The ID of the existing stand-alone account to be imported.

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

Response

Status Code

  • The request was accepted and the account was imported into the enterprise.

  • Invalid Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses

Create a new account in an enterprise

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 {{site.data.keyword.cloud_notm}}, but they don't need to be a user in the enterprise account.

POST /accounts
Request

The body required to create a new account.

Response

Status Code

  • The create account request completed successfully

  • Bad Request

  • Invalid or Expired Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses

Get accounts by query parameter

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
Request

Query Parameters

  • Get accounts that are either immediate children or are a part of the hierarchy for a given enterprise ID.

  • Get accounts that are either immediate children or are a part of the hierarchy for a given account group ID.

  • Get accounts that are either immediate children or are a part of the hierarchy for a given parent CRN.

  • Return results up to this limit. Valid values are between 0 and 100.

    Default: 100

Response

Status Code

  • Success

  • Invalid or Expired Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses

Get account by ID

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

Path Parameters

  • The ID of the account to retrieve.

Response

Status Code

  • Successfully retrieved account by ID

  • Invalid or Expired Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses

Move an account with the enterprise

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

PATCH /accounts/{account_id}
Request

Path Parameters

  • The ID of the account to move.

The ID of the account to move.

Response

Status Code

  • Success

  • Bad Request. The payload passed to the request is invalid.

  • Invalid or Expired Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses

Create an account group

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
Request

The body that is required to create an account group.

Response

Status Code

  • Create account group request completed successfully.

  • Bad Request

  • Invalid or Expired Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses

Get account groups by query parameter

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
Request

Query Parameters

  • Get account groups that are either immediate children or are a part of the hierarchy for a given enterprise ID.

  • Get account groups that are either immediate children or are a part of the hierarchy for a given account group ID.

  • Get account groups that are either immediate children or are a part of the hierarchy for a given parent CRN.

  • Return results up to this limit. Valid values are between 0 and 100.

    Default: 100

Response

Status Code

  • Success

  • Invalid or Expired Access Token

  • Access Denied

  • Internal Server Error

  • Service Unavailable

Example responses

Get account group by ID

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

Path Parameters

  • The ID of the account group to retrieve.

Response

Status Code

  • Successfully retrieved account group by ID.

  • Invalid or Expired Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses

Update an account group

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

Path Parameters

  • The ID of the account group to update.

The ID of the account group to update.

Response

Status Code

  • Success

  • Bad Request. The payload passed to the request is invalid.

  • Invalid or Expired Access Token

  • Access Denied

  • Not Found

  • Internal Server Error

  • Service Unavailable

Example responses