Introduction

With the IBM Cloud® Identity and Access Management (IAM) Policy Management API, you can create, update, view, and delete IAM policies. An IAM policy enables a subject to access a resource. These policies are used in access decisions when you call APIs for IAM-enabled services. For more information about how access management works, see Managing access in IBM Cloud.

There are three primary values in a policy: a subject, roles, and resources.

The subject is who or what is being granted access. The subject can be an IAM ID or an access group ID. The IAM ID is the ID of the entity that you are giving access to. The value can be a user or a service ID. The access group ID is the ID of the access group. An access group contains a set of users or service IDs. Access groups are the preferred method of managing access control. For more information, see Setting up access groups.

The following table shows the example formats for the supported subject types:

Type | Attribute name | Attribute value | ------------ | ------------- | ------------- | User | iam_id | IBMid-123456... |
Service ID | iam_id | iam-ServiceId-12345... | Access group | access_group_id | AccessGroupId-12345... |

The second value in a policy in the role. A role is a collection of actions that can be taken on a resource. There are platform, service, and custom roles. For more information, see IAM roles. And, the final value of the policy is the targeted resources whether it's an entire service, resource group, or specific service instance.

Two types of policies are supported: access policies and authorization policies. For more information, see Create a policy.

With policy templates and assignments you can centrally manage the policies for child accounts in your organization from the root enterprise account. For more information, see Working with template versions and Best practices for assigning access in an enterprise.

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 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/iampolicymanagementv1"
)

Go get

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

View on GitHub

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

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>iam-policy-management</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:iam-policy-management:{version}'

Replace {version} in these examples with the release version.

View on GitHub

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

Installing the Node SDK

npm install ibm-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 IAM Policy Management API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://iam.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.iam.cloud.ibm.com
Private endpoint URLs for classic infrastructure:
- Sydney: https://private.au-syd.iam.cloud.ibm.com
- Sao Paulo: https://private.br-sao.iam.cloud.ibm.com
- Montreal: https://private.ca-mon.iam.cloud.ibm.com
- Toronto: https://private.ca-tor.iam.cloud.ibm.com
- Frankfurt DC: https://private.eu-de.iam.cloud.ibm.com
- London: https://private.eu-gb.iam.cloud.ibm.com
- Madrid: https://private.eu-es.iam.cloud.ibm.com
- Tokyo: https://private.jp-tok.iam.cloud.ibm.com
- Osaka: https://private.jp-osa.iam.cloud.ibm.com
- Washington DC: https://private.us-east.iam.cloud.ibm.com
- Dallas: https://private.us-south.iam.cloud.ibm.com

Authentication

Authorization to the IAM Policy Management API is enforced by using an IBM Cloud IAM access token. The token is used to 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.

Any access, such as IAM actions, that is required to call a method is listed per individual method. The IAM actions associated with basic tasks for working with policies, including create, update, and delete actions, are inherited by the platform roles that can be assigned for each IAM-enabled service. For more information about the required IAM actions for custom roles and how they map to the access roles, see the list of actions and roles for the role management service.

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 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 IAM_POLICY_MANAGEMENT_URL=<SERVICE_URL>
export IAM_POLICY_MANAGEMENT_AUTHTYPE=iam
export IAM_POLICY_MANAGEMENT_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/iampolicymanagementv1"
}
...
serviceClientOptions := &iampolicymanagementv1.IamPolicyManagementV1Options{}
serviceClient, err := iampolicymanagementv1.NewIamPolicyManagementV1UsingExternalConfig(serviceClientOptions)

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 IAM_POLICY_MANAGEMENT_URL=<SERVICE_URL>
export IAM_POLICY_MANAGEMENT_AUTHTYPE=iam
export IAM_POLICY_MANAGEMENT_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.iam_policy_management.v1.IamPolicyManagement;
...
IamPolicyManagement serviceClient = IamPolicyManagement.newInstance();

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 IAM_POLICY_MANAGEMENT_URL=<SERVICE_URL>
export IAM_POLICY_MANAGEMENT_AUTHTYPE=iam
export IAM_POLICY_MANAGEMENT_APIKEY=<API_KEY>

Example of constructing the service client

const IamPolicyManagementV1 = require('ibm-platform-services/iam-policy-management/v1');
...
const serviceClient = IamPolicyManagementV1.newInstance({});

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 IAM_POLICY_MANAGEMENT_URL=<SERVICE_URL>
export IAM_POLICY_MANAGEMENT_AUTHTYPE=iam
export IAM_POLICY_MANAGEMENT_APIKEY=<API_KEY>

Example of constructing the service client

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

Auditing

You can monitor API activity within your account by using the IBM Cloud® Activity Tracker service. You can track when specific API methods are called by reviewing generated events in Activity Tracker.

If an event is tracked for a method, you can find it listed with the method. For more information about how to track IAM activity, see Auditing events for IAM.

Error handling

The Policy Management APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows:

{
    "trace": "cd4f7573121a4cf99f0079f8482b3d6b",
    "errors": [
        {
            "code": "invalid_token",
            "message": "The provided IAM token is invalid."
        }
    ],
    "status_code": 401
}

If an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations that are defined in the Reference section describe example errors that can be returned from a failed request. All responses from the IAM Policy Management API are in the JSON format.

Here are potential error codes that the API can return.

| 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 invalid, missing or expired. Get a new valid token and try again. | | 403 | Forbidden | The token is valid, but the subject of the token 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 can't be found. | | 409 | Conflict | The entity is already in the requested state. | | 415 | Unsupported Media Type | Request body sent was formatted by using an unsupported media type. | | 429 | Too Many Requests | Too many requests have been made within a given time window. Wait the time in seconds indicated in the Retry-After response header before calling the API again. | | 500 | Service Unavailable | IAM Policy Management Point is currently unavailable. Your request can't be processed. Wait a few minutes and try again. |

Additional headers

Some additional headers might be required to make successful requests to the API. Those additional headers are:

Transaction-Id

An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose.

If no transaction ID is passed in, then a random ID is generated.

Sorting

Sorting is available on the policies listing APIs. Use a sort query parameter set to the field name you want the results sorted by. All the top level policy fields are supported.

To reverse sort, add a - prefix to the field name.

For example, for the GET /v1/policies endpoint, a query parameter of sort=last_modified_at sorts the returned policies in ascending date and time order by last_modified_at. Meanwhile a query parameter of sort=-last_modified_at returns the policies in descending date and time order by last_modified_at.

Policy data enrichment

Currently two options are available: display and include_last_permit. By including query parameter format=display, the API returns the list of all actions included in each of the policy roles.

"roles": [
            {
              "role_id": "crn:v1:bluemix:public:iam::::role:Administrator",
              "display_name": "Administrator",
              "description": "Administrators can change object metadata or visibility for private services added to the account and can restrict the visibility of a public service.",
              "actions": [
                {
                  "id": "global-search-tagging.resource.read",
                  "displayName": "Find cloud resources",
                  "description": "The ability to find the resource using Global Search and Tagging search API."
                },
                {
                  "id": "iam.policy.read",
                  "displayName": "IAM Policy Read",
                  "description": "The ability to see policies."
                },
                {
                  "id": "iam.policy.create",
                  "displayName": "IAM Policy Create",
                  "description": "The ability to create policies."
                }
              ]
            }
          ],

Including the query parameter format=include_last_permit returns details of when the policy last granted a permit decision and the number of times it has done so.

{
   "id": "03b5696c-6844-430f-a3b1-8f2d0de53218",
   "type": "access",
   "subjects": ...,
   "roles": ...,
   "resources": ...,
   "last_permit_at": "2020-10-16T22:17:40.832Z",
   "last_permit_frequency": 18
},

This data is provided for informational purposes only. The last permit data only include records begining from end of October 2020.

Rate limiting

A response with status 429 Too Many Requests is returned if too many requests are made within a time window. The response includes a Retry-After header to indicate the time in seconds to wait before sending the next request.

Related APIs

When you work with the Policy Management API, it might be helpful to be aware of other IAM services. See Identity Services to learn about API key, service ID, and token creation. See Access groups to create groups and manage memberships.

IAM Policy Management | IBM Cloud API Docs