Introduction

Quickly assign users access to more than one resource at a time by creating and updating resource groups with the IBM Cloud® Resource Manager API. You can delete any resource group only if it doesn't contain any resources, and it isn't the default resource group. 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 and all resources within it are also suspended.

In a Lite account, a user can have only one resource group. For a Pay-As-You-Go or Subscription account, a user can create more than one resource group.

To create resource instances within resource groups, see the IBM Cloud® Resource Controller API.

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>resource-manager</artifactId>
    <version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:resource-manager:{version}'

View on GitHub https://github.com/IBM/platform-services-java-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/resourcemanagerv2"
)

Go get

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

View on GitHub https://github.com/IBM/platform-services-go-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade ibm-platform-services

View on GitHub https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The Resource Manager API uses the following global endpoint URL for all regions. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://resource-controller.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.resource-controller.cloud.ibm.com
Private endpoint URLs for classic infrastructure:
- Dallas: https://private.us-south.resource-controller.cloud.ibm.com
- Washington DC: https://private.us-east.resource-controller.cloud.ibm.com

Example API request

curl -X {request_method} "https://resource-controller.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 Resource Manager API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

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

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST \
  "https://iam.test.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 IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/resourcemanagerv2"
}
...
serviceClientOptions := &resourcemanagerv2.ResourceManagerV2Options{}
serviceClient, err := resourcemanagerv2.NewResourceManagerV2UsingExternalConfig(serviceClientOptions)

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

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.resource_manager.v2.ResourceManager;
...
ResourceManager serviceClient = ResourceManager.newInstance();

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

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

const ResourceManagerV2 = require('@ibm-cloud/platform-services/resource-manager/v2');
...
const serviceClient = ResourceManagerV2.newInstance({});

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

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import ResourceManagerV2
...
service_client = ResourceManagerV2.new_instance()

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 Account and Billing activity, see Activity tracking events for account management.

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 cannot 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 cannot not be processed. Wait a few minutes and try again. |

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.

The response to each HTTP request includes headers that you can use to determine whether you are close to the rate limit:

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

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

Currently, the rate of allowed requests for all resource manager APIs is 500 requests per 10 seconds.

Related APIs

See the following related APIs for more actions for service and resource management.

Resource Manager | IBM Cloud API Docs