Many companies across industries seek ways to centrally manage cloud resources across their accounts. IBM Cloud offers several options for this:

Projects: Ideal for managing Infrastructure as Code (IaC).
APIs: A great option for companies with existing resource management systems looking to extend them to include IBM Cloud resources.

This tutorial focuses on using Application Programming Interfaces (APIs) for centralized resource management.

Automating resource management for child accounts

We can automate resource management for child accounts using a service ID and Enterprise managed IAM templates from the Enterprise root account.

Steps

Set up a service ID and API key: Use a service ID and API key from the Enterprise root account. Alternatively, you can use one from an existing child account.
Define IAM Templates: Use trusted profiles templates and access policy templates to assign the necessary access for resource management.
Assign templates to child accounts: Apply the IAM templates to the child accounts that need management.
Manage resources using trusted profiles: Use the assigned trusted profiles and the service ID’s API key to manage resources within each child account’s context.

Follow the step-by-step guide with links and examples from the API documentation.

Objectives

By the end of this lab, you will be able to use a single service ID to manage resources across all enterprise child accounts using only API requests.

Prerequisites

Before you begin, make sure you have the following:

Service ID API key or access to create one. This will be your operations service ID used to manage resources in the child accounts.
Setup credentials: A user or service ID (different from the operations service ID) with:
- Access to create and assign IAM templates
- At least Viewer role on the Enterprise service

Additionally, ensure that all enterprise child accounts have the Enterprise-IAM managed account setting enabled.

Step 1. Get an access token

Before you can manage service IDs and IAM templates, you need an access token that represents a user or service ID with the required permissions. Use one of the following options to get it.

Option 1: Use the API

Run the following curl command, replacing $MY_APIKEY with your actual API key:

curl -X POST "https://iam.cloud.ibm.com/identity/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$MY_APIKEY'

Response will look like this:

{
  "access_token": "reallylong.token.here",
  "refresh_token": "not_supported",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expiration": 1727978763,
  "scope": "ibm openid"
}

Option 2: Use IBM Cloud CLI

Log in to IBM Cloud:

ibmcloud login
Get the token:

ibmcloud iam oauth-tokens

Output:

IAM token: Bearer reallylong.token.here

Step 2. Create the operations service ID and API key (optional)

If you already have a service ID and API key for managing resources, you can skip this step.

Create a service ID**

Use the access token from the previous step to create a service ID. Refer to the Service ID API documentation if needed.

 curl -X POST "https://iam.cloud.ibm.com/v1/serviceids" \
 --header "Authorization: Bearer <TOKEN>" \
 --header "Content-Type: application/json" \
 --data '{
     "name": "Operator resource manager identity",
     "description": "Operator service id to manage resources in child accounts",
     "account_id": "<ACCOUNT_ID>"
 }'

Sample response:

 {
   "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",   
   "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
   "entity_tag": "1-b5edc4362f94fb1fa5f009467b1db039",
   "crn": "crn:v1:bluemix:public:iam-identity::a/ACCOUNT_ID::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
   "locked": false,
   "created_at": "2024-10-04T14:05+0000",
   "modified_at": "2024-10-04T14:05+0000",
   "account_id": "ACCOUNT_ID",
   "name": "Operator resource manager identity",
   "description": "Operator service id to manage resources in child accounts",
   "unique_instance_crns": []
 }

Create the API Key for the Service ID

Next, generate an API key for the service ID using the API Key API.

 curl -X POST "https://iam.cloud.ibm.com/v1/apikeys"\
 --header "Authorization: Bearer <TOKEN>"\
 --header "Content-Type: application/json"\
 --data '{
     "name": "Operator resource manager apikey",
     "description": "Operator key to manage resources in child accounts",
     "iam_id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
     "account_id": "<ACCOUNT_ID>",
     "store_value": false
 }'

Sample response:

 {
   "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
   "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
   "crn": "crn:v1:bluemix:public:iam-identity::a/ACCOUNT_ID::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
   "locked": false,
   "disabled": false,
   "created_at": "2024-10-04T12:28+0000",
   "created_by": "IBMid-110000AB1Z",
   "modified_at": "2024-10-04T12:28+0000",
   "support_sessions": false,
   "action_when_leaked": "none",
   "name": "Operator resource manager apikey",
   "description": "Operator key to manage resources in child accounts",
   "iam_id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
   "account_id": "ACCOUNT_ID",
   "apikey": "created_apikey"
 }

Step 3. Create access policy templates

To grant the necessary permissions for managing resources, we’ll create two access policy templates. These templates will later be assigned to a Trusted Profile in the next step.

API Reference: Create Policy Template

Template 1: Manage resource groups

This template grants access to manage catalog services in the child accounts.

Sample request:

curl --location 'https://iam.cloud.ibm.com/v1/policy_templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "name": "ServiceAdministrator",
  "description": "Manage services",
  "account_id": "<ACCOUNT_ID>",
  "committed": true,
  "policy": {
    "type": "access",
    "description": "Manage all services",
    "resource": {
      "attributes": [
        {
          "key": "serviceType",
          "operator": "stringEquals",
          "value": "service"
        }
      ]
    },
    "control": {
      "grant": {
        "roles": [{
          "role_id": "crn:v1:bluemix:public:iam::::role:Administrator"
        }]
      }
    }
  }
}'

Sample response:

{
  "id": "policyTemplate-8e27d6d9-4e9c-4cfd-a431-15d2010a7f82",
  "name": "ServiceAdministrator",
  "account_id": "ACCOUNT_ID",
  "description": "Manage services",
  "version": "1",
  "policy": {
    "type": "access",
    "description": "Manage all services",
    "resource": {
      "attributes": [
        {
          "key": "serviceType",
          "operator": "stringEquals",
          "value": "service"
        }
      ]
    },
    "control": {
      "grant": {
        "roles": [
          {
            "role_id": "crn:v1:bluemix:public:iam::::role:Administrator"
          }
        ]
      }
    }
  },
  "created_at": "2024-10-03T17:22:09.004Z",
  "created_by_id": "iam-ServiceId-66306ad9-5fe6-472e-94bc-ad73c33352ca",
  "last_modified_at": "2024-10-03T17:22:09.004Z",
  "last_modified_by_id": "iam-ServiceId-66306ad9-5fe6-472e-94bc-ad73c33352ca",
  "counts": {
    "template": {
      "current": 27,
      "limit": 100
    },
    "version": {
      "current": 1,
      "limit": 100
    }
  },
  "href": "https://iam.test.cloud.ibm.com/v1/policy_templates/policyTemplate-8e27d6d9-4e9c-4cfd-a431-15d2010a7f82",
  "state": "active",
  "committed": true
}

Template 2: Manage all catalog services

This template grants Administrator access to manage Resource Groups.

curl --location 'https://iam.cloud.ibm.com/v1/policy_templates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "name": "ResourceGroupAdministrator",
  "description": "Resource Group Administrator",
  "account_id": "<ACCOUNT_ID>",
  "committed": true,
  "policy": {
    "type": "access",
    "description": "Manage all Resource Groups",
    "resource": {
      "attributes": [
        {
          "key": "resourceType",
          "operator": "stringEquals",
          "value": "resource-group"
        }
      ]
    },
    "control": {
      "grant": {
        "roles": [{
          "role_id": "crn:v1:bluemix:public:iam::::role:Administrator"
        }]
      }
    }
  }
}'

Step 4. Create a trusted profile template

Next, create a trusted profile template that:

Trusts the operator service ID (created in Step 1), and
Includes the two access policy templates (from Step 2).

API reference: Trusted profile templates API

curl -X POST "https://iam.cloud.ibm.com/v1/profile_templates" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <TOKEN>" \
--data '{
    "account_id": "<ENTERPRISE_ACCOUNT_ID>",
    "name": "Resource Manager template",
    "commited": true,
    "profile": {
        "name": "Profile for Service Adminstrator",
        "description": "Manage all services in the account",
        "identities": [
            {
                "type": "serviceid",
                "identifier": "<enter the service id like: ServiceId-123456789>"
            }
        ]
    },
    "policy_template_references": [
        {
            "id": "<Service Administrator policy template id>",
            "version": 1
        },
        {
            "id": "<Resource Group Administrator policy template id>",
            "version": 1
        },
    ]
}'

Step 5. Assign the trusted profile template

Assign the trusted profile template to either:

An individual child account, or
An account group (recommended for scalability).

When assigned to an account group, the system will:

Automatically create a trusted profile in each child account within the group.
Automatically create trusted profiles for newly added accounts.
Automatically remove them when accounts are removed or deleted from the group.

API reference: Trusted Profile Assignments API

This step ensures the operator service ID has the required access in all target accounts.

curl -X POST "https://iam.cloud.ibm.com/v1/profile_assignments"\
--header "Content-Type: application/json"\
--header "Authorization: Bearer <TOKEN>"\
--data '{
    "template_id": "<Trusted Profile template id>",
    "template_version": 1,
    "target_type": "AccountGroup",
    "target": "<account group id>"
}'

Runtime Steps

Follow these steps to manage resources in Enterprise child accounts using APIs:

Get a token for the service ID

Use the operations Service ID’s API key (created during setup) to get an IAM access token.

Get token API

 curl -X POST "https://iam.cloud.ibm.com/identity/token" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=<OPERATOR_APIKEY>'

Sample response:

 {
   "access_token": "reallylong.token.here",
   "refresh_token": "not_supported",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1727978763,
   "scope": "ibm openid"
 }

List available trusted profiles

Use the token from Step 1 to retrieve the list of trusted profiles and associated child accounts that the Service ID can access.

 curl --location 'https://iam.cloud.ibm.com/identity/profiles' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'access_token=<service id token>'

Sample response:

 {
   "count": 5,
   "profiles": [
     {
       "id": "Profile-6e1f7ea6-734c-49f5-832a-cd8f4aaed739",
       "entity_tag": "2-b36be9d5a3152ef753a76c0baf4293f2",
       "crn": "crn:v1:staging:public:iam-identity::a/6e42a47f8ae143fa9accc55dfe22096f::profile:Profile-6e1f7ea6-734c-49f5-832a-cd8f4aaed739",
       "name": "Access Report",
       "description": "read only access to reports",
       "created_at": "2024-04-12T19:00+0000",
       "modified_at": "2024-04-12T19:30+0000",
       "iam_id": "iam-Profile-6e1f7ea6-734c-49f5-832a-cd8f4aaed739",
       "account_id": "6e42a47f8ae143fa9accc55dfe22096f",
       "template_id": "ProfileTemplate-69178281-39e6-46b3-ad3f-53735a3f9282",
       "assignment_id": "TemplateAssignment-2498765a-86f4-4093-8e70-7f7f06182669"
     },
     {
       "id": "Profile-9f6c71c2-6fab-4e5e-a47c-bdf00ef350da",
       "entity_tag": "2-2586919946891dc9ec5e4e3ebf1a6ed4",
       "crn": "crn:v1:staging:public:iam-identity::a/5dd10bd7e9a44ac990813d234649a752::profile:Profile-9f6c71c2-6fab-4e5e-a47c-bdf00ef350da",
       "name": "Access Report",
       "description": "read only access to reports",
       "created_at": "2024-04-12T19:00+0000",
       "modified_at": "2024-04-12T19:30+0000",
       "iam_id": "iam-Profile-9f6c71c2-6fab-4e5e-a47c-bdf00ef350da",
       "account_id": "5dd10bd7e9a44ac990813d234649a752",
       "template_id": "ProfileTemplate-69178281-39e6-46b3-ad3f-53735a3f9282",
       "assignment_id": "TemplateAssignment-2498765a-86f4-4093-8e70-7f7f06182669"
     },
     {
       "id": "Profile-d99e8cf3-da65-42ec-94ed-fcf72f186e1e",
       "entity_tag": "2-9e5c3cd8b1d13ab26d528e4d52183954",
       "crn": "crn:v1:staging:public:iam-identity::a/8c2f25994fb74fe18539205580885559::profile:Profile-d99e8cf3-da65-42ec-94ed-fcf72f186e1e",
       "name": "Access Report",
       "description": "read only access to reports",
       "created_at": "2024-04-12T19:00+0000",
       "modified_at": "2024-04-12T19:30+0000",
       "iam_id": "iam-Profile-d99e8cf3-da65-42ec-94ed-fcf72f186e1e",
       "account_id": "8c2f25994fb74fe18539205580885559",
       "template_id": "ProfileTemplate-69178281-39e6-46b3-ad3f-53735a3f9282",
       "assignment_id": "TemplateAssignment-2498765a-86f4-4093-8e70-7f7f06182669"
     },
     {
       "id": "Profile-2cbc3b11-ef06-4d90-8709-68a758fe4cd0",
       "entity_tag": "2-ed21407aa67df82b58987c265d54b270",
       "crn": "crn:v1:staging:public:iam-identity::a/948ee4a53bfd435f8b8c195e08f2bbac::profile:Profile-2cbc3b11-ef06-4d90-8709-68a758fe4cd0",
       "name": "Access Report",
       "description": "read only access to reports",
       "created_at": "2024-04-12T19:00+0000",
       "modified_at": "2024-04-12T19:30+0000",
       "iam_id": "iam-Profile-2cbc3b11-ef06-4d90-8709-68a758fe4cd0",
       "account_id": "948ee4a53bfd435f8b8c195e08f2bbac",
       "template_id": "ProfileTemplate-69178281-39e6-46b3-ad3f-53735a3f9282",
       "assignment_id": "TemplateAssignment-2498765a-86f4-4093-8e70-7f7f06182669"
     },
     {
       "id": "Profile-5ec4f299-bb24-4867-a254-120788e64b47",
       "entity_tag": "2-2c47981665dc44c265008baece9e4ea6",
       "crn": "crn:v1:staging:public:iam-identity::a/002f345a049b4f11ae6206661e5cb438::profile:Profile-5ec4f299-bb24-4867-a254-120788e64b47",
       "name": "Access Report",
       "description": "read only access to reports",
       "created_at": "2024-04-12T19:00+0000",
       "modified_at": "2024-04-12T19:30+0000",
       "iam_id": "iam-Profile-5ec4f299-bb24-4867-a254-120788e64b47",
       "account_id": "002f345a049b4f11ae6206661e5cb438",
       "template_id": "ProfileTemplate-69178281-39e6-46b3-ad3f-53735a3f9282",
       "assignment_id": "TemplateAssignment-2498765a-86f4-4093-8e70-7f7f06182669"
     }
   ]
 }

Get a trusted profile token for a child account

For each child account, use the service ID token, the trusted profile ID, and the child account ID to request a trusted profile token.

Assume trusted profile token API

 curl -X POST "https://iam.cloud.ibm.com/identity/token"\
   --header "Content-Type: application/x-www-form-urlencoded"\
   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:assume'\
   --data-urlencode 'access_token=<ACCESS-TOKEN>'\
   --data-urlencode 'profile_id=<Profile-5ec4f299-bb24-4867-a254-120788e64b47>'

Manage resources in the child account

Use the trusted profile token from Step 3 to make API calls in the context of the child account.

Explore supported IBM Cloud APIs at IBM Cloud API Docs.

Resources

Centrally manage IBM Cloud resources with APIs

Centrally manage IBM Cloud resources with APIs