Introduction

IBM Cloud resource manager manages the collection of resources by resource groups.

A resource group belongs to an account. All IBM Cloud resources must be provisioned within a resource group. If an account is suspended, the corresponding resource group will be suspended as well, and all resources within the resource group will be suspended.

When a user creates an account, a default resource group is created in the account. All IBM Cloud resources must be provisioned within a resource group. If an account is suspended, the corresponding resource group will be suspended as well, and all resources within the resource group will be suspended. For standard account, a user can only have one resource group. For a Paygo or Subscription account, a user is allowed to create more than one resource group.

API endpoint

https://resource-manager.bluemix.net/v2/

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
201 Success The resource group was successfully created.
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. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
410 Gone The resource is valid but has been removed already in a previous call
500 Internal Server Error offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token in the API request authentication header:

-H 'Authorization: Bearer <IAM_TOKEN>'

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

To retrieve your access token:

curl -X POST
https://iam.bluemix.net/identity/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Accept: application/json"
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&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.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --id

Replace <instance_name> with the unique alias that you assigned to your service instance.

When working with the resource controller endpoints, it may be helpful to be aware of the IBM Cloud Open Source Broker APIs used to create your service broker.

Methods

Get a list of all resource groups.

Get a list of all resource groups.

GET /resource_groups
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Query Parameters

  • The account id of the resource groups you want to get.

Response

Status Code

  • The resource groups was successfully retrieved.

  • The request could have invalid paylaod.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Create a new resource group.

Create a new resource group into an account.

POST /resource_groups
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Response

Status Code

  • Resource group has been created.

  • The request could have invalid paylaod.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Get a resource group.

Retrieve a resource group by ID.

GET /resource_groups/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the alias.

Response

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Update a resource group.

Update a resource group by ID.

PATCH /resource_groups/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the resource group.

Response

Status Code

  • Successfully updated resource group.

  • The request could have invalid paylaod.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Get a list of all quota definitions.

Get a list of all quota definitions.

GET /quota_definition
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Response

Status Code

  • The quota definitions were successfully retrieved.

  • The request could have invalid paylaod.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Get a quota definition.

Get a a quota definition.

GET /quota_definition/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The id of the quota.

Response

Status Code

  • The quota is successfully retrieved.

  • The request could have invalid paylaod.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses