IAM Policy Management | IBM Cloud API Docs

Introduction

Last updated: 2023-09-08

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:
- Dallas: https://private.us-south.iam.cloud.ibm.com
- Washington DC: https://private.us-east.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.

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.

Get policies and filter by attributes. While managing policies, you might want to retrieve policies in the account and filter by attribute values. This can be done through query parameters. The following attributes are supported: account_id, iam_id, access_group_id, type, service_type, sort, format and state. account_id is a required query parameter. Only policies that have the specified attributes and that the caller has read access to are returned. If the caller does not have read access to any policies an empty array is returned.

GET /v1/policies

(iamPolicyManagement *IamPolicyManagementV1) ListPolicies(listPoliciesOptions *ListPoliciesOptions) (result *PolicyCollection, response *core.DetailedResponse, err error)

(iamPolicyManagement *IamPolicyManagementV1) ListPoliciesWithContext(ctx context.Context, listPoliciesOptions *ListPoliciesOptions) (result *PolicyCollection, response *core.DetailedResponse, err error)

ServiceCall<PolicyCollection> listPolicies(ListPoliciesOptions listPoliciesOptions)

listPolicies(params)

list_policies(
        self,
        account_id: str,
        *,
        accept_language: str = None,
        iam_id: str = None,
        access_group_id: str = None,
        type: str = None,
        service_type: str = None,
        tag_name: str = None,
        tag_value: str = None,
        sort: str = None,
        format: str = None,
        state: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam.policy.read

Auditing

Calling this method generates the following auditing event.

iam-am.policy.read

Request

Instantiate the ListPoliciesOptions struct and set the fields to provide parameter values for the ListPolicies method.

Use the ListPoliciesOptions.Builder to create a ListPoliciesOptions object that contains the parameter values for the listPolicies method.

Custom Headers

Accept-Language
string
Language code for translations
- default - English
- de - German (Standard)
- en - English
- es - Spanish (Spain)
- fr - French (Standard)
- it - Italian (Standard)
- ja - Japanese
- ko - Korean
- pt-br - Portuguese (Brazil)
- zh-cn - Chinese (Simplified, PRC)
- zh-tw - (Chinese, Taiwan)
Possible values: length ≥ 1
Default: default

Query Parameters

account_id
Required*
string
The account GUID that the policies belong to.
iam_id
string
Optional IAM ID used to identify the subject.
access_group_id
string
Optional access group id.
type
string
Optional type of policy.

Allowable values: [access,authorization]
service_type
string
Optional type of service.

Allowable values: [service,platform_service]
tag_name
string
Optional name of the access tag in the policy.
tag_value
string
Optional value of the access tag in the policy.
sort
string
Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field. Example '-last_modified_at'

Allowable values: [id,type,href,created_at,created_by_id,last_modified_at,last_modified_by_id,state]
format
string
Include additional data per policy returned
- include_last_permit - returns details of when the policy last granted a permit decision and the number of times it has done so
- display - returns the list of all actions included in each of the policy roles
Allowable values: [include_last_permit,display]
state
string
The state of the policy.
- active - returns active policies
- deleted - returns non-active policies
Allowable values: [active,deleted]

parameter

WithContext method only

ListPoliciesOptions

The ListPolicies options.

ListPoliciesOptions

The listPolicies options.

parameters

accountId
Required*
string
The account GUID that the policies belong to.
acceptLanguage
string
Language code for translations
- default - English
- de - German (Standard)
- en - English
- es - Spanish (Spain)
- fr - French (Standard)
- it - Italian (Standard)
- ja - Japanese
- ko - Korean
- pt-br - Portuguese (Brazil)
- zh-cn - Chinese (Simplified, PRC)
- zh-tw - (Chinese, Taiwan).
Possible values: length ≥ 1
Default: default
iamId
string
Optional IAM ID used to identify the subject.
accessGroupId
string
Optional access group id.
type
string
Optional type of policy.

Allowable values: [access,authorization]
serviceType
string
Optional type of service.

Allowable values: [service,platform_service]
tagName
string
Optional name of the access tag in the policy.
tagValue
string
Optional value of the access tag in the policy.
sort
string
Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field. Example '-last_modified_at'.

Allowable values: [id,type,href,created_at,created_by_id,last_modified_at,last_modified_by_id,state]
format
string
Include additional data per policy returned
- include_last_permit - returns details of when the policy last granted a permit decision and the number of times it has done so
- display - returns the list of all actions included in each of the policy roles.
Allowable values: [include_last_permit,display]
state
string
The state of the policy.
- active - returns active policies
- deleted - returns non-active policies.
Allowable values: [active,deleted]

parameters

account_id
Required*
str
The account GUID that the policies belong to.
accept_language
str
Language code for translations
- default - English
- de - German (Standard)
- en - English
- es - Spanish (Spain)
- fr - French (Standard)
- it - Italian (Standard)
- ja - Japanese
- ko - Korean
- pt-br - Portuguese (Brazil)
- zh-cn - Chinese (Simplified, PRC)
- zh-tw - (Chinese, Taiwan).
Possible values: length ≥ 1
Default: default
iam_id
str
Optional IAM ID used to identify the subject.
access_group_id
str
Optional access group id.
type
str
Optional type of policy.

Allowable values: [access,authorization]
service_type
str
Optional type of service.

Allowable values: [service,platform_service]
tag_name
str
Optional name of the access tag in the policy.
tag_value
str
Optional value of the access tag in the policy.
sort
str
Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field. Example '-last_modified_at'.

Allowable values: [id,type,href,created_at,created_by_id,last_modified_at,last_modified_by_id,state]
format
str
Include additional data per policy returned
- include_last_permit - returns details of when the policy last granted a permit decision and the number of times it has done so
- display - returns the list of all actions included in each of the policy roles.
Allowable values: [include_last_permit,display]
state
str
The state of the policy.
- active - returns active policies
- deleted - returns non-active policies.
Allowable values: [active,deleted]

Example request

curl -X GET 'https://iam.cloud.ibm.com/v1/policies?account_id=$ACCOUNT_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

Example request

options := iamPolicyManagementService.NewListPoliciesOptions(
  exampleAccountID,
)
options.SetIamID(exampleUserID)
options.SetFormat("include_last_permit")

policyList, response, err := iamPolicyManagementService.ListPolicies(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(policyList, "", "  ")
fmt.Println(string(b))

Example request

ListPoliciesOptions options = new ListPoliciesOptions.Builder()
        .accountId(exampleAccountId)
        .iamId(EXAMPLE_USER_ID)
        .format("include_last_permit")
        .build();

Response<PolicyCollection> response = service.listPolicies(options).execute();
PolicyCollection policyCollection = response.getResult();

System.out.println(policyCollection);

Example request

const params = {
  accountId: exampleAccountId,
  iamId: exampleUserId,
  format: 'include_last_permit',
};

try {
  const res = await iamPolicyManagementService.listPolicies(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

Example request

policy_list = iam_policy_management_service.list_policies(
  account_id=example_account_id, iam_id=example_user_id, format='include_last_permit'
).get_result()

print(json.dumps(policy_list, indent=2))

Response

Response Body

PolicyCollection

A collection of policies.

PolicyCollection

A collection of policies.

PolicyCollection

A collection of policies.

PolicyCollection

A collection of policies.

PolicyCollection

A collection of policies.

Status Code

200
Policies retrieval successful.
400
The request you made is not valid.
401
The token you provided is not valid.
406
The requested resource(s) cannot be formatted using the requested media type(s).
429
Too many requests have been made within a given time window.

Example responses

Status 200

{
  "policies": [
    {
      "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "type": "access",
      "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
      "subjects": [
        {
          "attributes": [
            {
              "name": "iam_id",
              "value": "IBMid-123453user"
            }
          ]
        }
      ],
      "roles": [
        {
          "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
        }
      ],
      "resources": [
        {
          "attributes": [
            {
              "name": "accountId",
              "value": "ACCOUNT_ID",
              "operator": "stringEquals"
            },
            {
              "name": "serviceName",
              "value": "SERVICE_NAME",
              "operator": "stringEquals"
            }
          ]
        }
      ],
      "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
      "created_at": "2018-08-30T14:09:09.907Z",
      "created_by_id": "USER_ID",
      "last_modified_at": "2018-08-30T14:09:09.907Z",
      "last_modified_by_id": "USER_ID",
      "state": "active"
    }
  ]
}

Success example

{
  "policies": [
    {
      "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "type": "access",
      "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
      "subjects": [
        {
          "attributes": [
            {
              "name": "iam_id",
              "value": "IBMid-123453user"
            }
          ]
        }
      ],
      "roles": [
        {
          "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
        }
      ],
      "resources": [
        {
          "attributes": [
            {
              "name": "accountId",
              "value": "ACCOUNT_ID",
              "operator": "stringEquals"
            },
            {
              "name": "serviceName",
              "value": "SERVICE_NAME",
              "operator": "stringEquals"
            }
          ]
        }
      ],
      "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
      "created_at": "2018-08-30T14:09:09.907Z",
      "created_by_id": "USER_ID",
      "last_modified_at": "2018-08-30T14:09:09.907Z",
      "last_modified_by_id": "USER_ID",
      "state": "active"
    }
  ]
}

Status 400

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "missing_required_query_parameter",
      "message": "'account_id' is a required query parameter"
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "missing_required_query_parameter",
      "message": "'account_id' is a required query parameter"
    }
  ],
  "status_code": 400
}

Status 401

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

Error example

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

Status 406

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Creates a policy to grant access between a subject and a resource. There are two types of policies: access and authorization. A policy administrator might want to create an access policy which grants access to a user, service-id, or an access group. They might also want to create an authorization policy and setup access between services.

Access

To create an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, resourceGroupId or service_group_id attribute and the accountId attribute. The IAM Services group (IAM) is a subset of account management services that includes the IAM platform services IAM Identity, IAM Access Management, IAM Users Management, IAM Groups, and future IAM services. If the subject is a locked service-id, the request will fail.

Authorization

Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes may support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Creates a policy to grant access between a subject and a resource. There are two types of policies: access and authorization. A policy administrator might want to create an access policy which grants access to a user, service-id, or an access group. They might also want to create an authorization policy and setup access between services.

Access

To create an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, resourceGroupId or service_group_id attribute and the accountId attribute. The IAM Services group (IAM) is a subset of account management services that includes the IAM platform services IAM Identity, IAM Access Management, IAM Users Management, IAM Groups, and future IAM services. If the subject is a locked service-id, the request will fail.

Authorization

Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes may support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Creates a policy to grant access between a subject and a resource. There are two types of policies: access and authorization. A policy administrator might want to create an access policy which grants access to a user, service-id, or an access group. They might also want to create an authorization policy and setup access between services.

Access

To create an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, resourceGroupId or service_group_id attribute and the accountId attribute. The IAM Services group (IAM) is a subset of account management services that includes the IAM platform services IAM Identity, IAM Access Management, IAM Users Management, IAM Groups, and future IAM services. If the subject is a locked service-id, the request will fail.

Authorization

Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes may support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Creates a policy to grant access between a subject and a resource. There are two types of policies: access and authorization. A policy administrator might want to create an access policy which grants access to a user, service-id, or an access group. They might also want to create an authorization policy and setup access between services.

Access

To create an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, resourceGroupId or service_group_id attribute and the accountId attribute. The IAM Services group (IAM) is a subset of account management services that includes the IAM platform services IAM Identity, IAM Access Management, IAM Users Management, IAM Groups, and future IAM services. If the subject is a locked service-id, the request will fail.

Authorization

Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes may support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Creates a policy to grant access between a subject and a resource. There are two types of policies: access and authorization. A policy administrator might want to create an access policy which grants access to a user, service-id, or an access group. They might also want to create an authorization policy and setup access between services.

Access

To create an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, resourceGroupId or service_group_id attribute and the accountId attribute. The IAM Services group (IAM) is a subset of account management services that includes the IAM platform services IAM Identity, IAM Access Management, IAM Users Management, IAM Groups, and future IAM services. If the subject is a locked service-id, the request will fail.

Authorization

Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes may support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

POST /v1/policies

(iamPolicyManagement *IamPolicyManagementV1) CreatePolicy(createPolicyOptions *CreatePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

(iamPolicyManagement *IamPolicyManagementV1) CreatePolicyWithContext(ctx context.Context, createPolicyOptions *CreatePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

ServiceCall<Policy> createPolicy(CreatePolicyOptions createPolicyOptions)

createPolicy(params)

create_policy(
        self,
        type: str,
        subjects: List['PolicySubject'],
        roles: List['PolicyRole'],
        resources: List['PolicyResource'],
        *,
        description: str = None,
        accept_language: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam.policy.create

Auditing

Calling this method generates the following auditing event.

iam-am.policy.create

Request

Instantiate the CreatePolicyOptions struct and set the fields to provide parameter values for the CreatePolicy method.

Use the CreatePolicyOptions.Builder to create a CreatePolicyOptions object that contains the parameter values for the createPolicy method.

Custom Headers

Accept-Language
string
Language code for translations
- default - English
- de - German (Standard)
- en - English
- es - Spanish (Spain)
- fr - French (Standard)
- it - Italian (Standard)
- ja - Japanese
- ko - Korean
- pt-br - Portuguese (Brazil)
- zh-cn - Chinese (Simplified, PRC)
- zh-tw - (Chinese, Taiwan)
Possible values: length ≥ 1
Default: default

Request Body

Required*

PolicyRequest

A policy to be created.

parameter

WithContext method only

CreatePolicyOptions

The CreatePolicy options.

CreatePolicyOptions

The createPolicy options.

parameters

type
Required*
string
The policy type; either 'access' or 'authorization'.

Possible values: 6 ≤ length ≤ 13, Value must match regular expression /^[a-z]+$/
subjects
Required*
The subjects associated with a policy.

Possible values: number of items = 1
roles
Required*
A set of role cloud resource names (CRNs) granted by the policy.

Possible values: number of items ≥ 1
resources
Required*
The resources associated with a policy.

Possible values: number of items = 1
description
string
Customer-defined description.

Possible values: 1 ≤ length ≤ 300
acceptLanguage
string
Language code for translations
- default - English
- de - German (Standard)
- en - English
- es - Spanish (Spain)
- fr - French (Standard)
- it - Italian (Standard)
- ja - Japanese
- ko - Korean
- pt-br - Portuguese (Brazil)
- zh-cn - Chinese (Simplified, PRC)
- zh-tw - (Chinese, Taiwan).
Possible values: length ≥ 1
Default: default

parameters

type
Required*
str
The policy type; either 'access' or 'authorization'.

Possible values: 6 ≤ length ≤ 13, Value must match regular expression /^[a-z]+$/
subjects
Required*
The subjects associated with a policy.

Possible values: number of items = 1
roles
Required*
A set of role cloud resource names (CRNs) granted by the policy.

Possible values: number of items ≥ 1
resources
Required*
The resources associated with a policy.

Possible values: number of items = 1
description
str
Customer-defined description.

Possible values: 1 ≤ length ≤ 300
accept_language
str
Language code for translations
- default - English
- de - German (Standard)
- en - English
- es - Spanish (Spain)
- fr - French (Standard)
- it - Italian (Standard)
- ja - Japanese
- ko - Korean
- pt-br - Portuguese (Brazil)
- zh-cn - Chinese (Simplified, PRC)
- zh-tw - (Chinese, Taiwan).
Possible values: length ≥ 1
Default: default

Example request

curl -X POST 'https://iam.cloud.ibm.com/v1/policies' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{
  "type": "access",
  "description": "Editor role for SERVICE_NAME\'s RESOURCE_NAME",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }'
  ],
  "roles":[
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Editor"
    }
  ],
  "resources":[
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "$ACCOUNT_ID"
        },
        {
          "name": "serviceName",
          "value": "$SERVICE_NAME"
        },
        {
          "name": "resource",
          "value": "$RESOURCE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ]
}'

Example request

subjectAttribute := &iampolicymanagementv1.SubjectAttribute{
  Name:  core.StringPtr("iam_id"),
  Value: &exampleUserID,
}
policySubjects := &iampolicymanagementv1.PolicySubject{
  Attributes: []iampolicymanagementv1.SubjectAttribute{*subjectAttribute},
}
policyRoles := &iampolicymanagementv1.PolicyRole{
  RoleID: core.StringPtr("crn:v1:bluemix:public:iam::::role:Viewer"),
}
accountIDResourceAttribute := &iampolicymanagementv1.ResourceAttribute{
  Name:     core.StringPtr("accountId"),
  Value:    core.StringPtr(exampleAccountID),
  Operator: core.StringPtr("stringEquals"),
}
serviceNameResourceAttribute := &iampolicymanagementv1.ResourceAttribute{
  Name:     core.StringPtr("serviceType"),
  Value:    core.StringPtr("service"),
  Operator: core.StringPtr("stringEquals"),
}
policyResourceTag := &iampolicymanagementv1.ResourceTag{
  Name:     core.StringPtr("project"),
  Value:    core.StringPtr("prototype"),
  Operator: core.StringPtr("stringEquals"),
}
policyResources := &iampolicymanagementv1.PolicyResource{
  Attributes: []iampolicymanagementv1.ResourceAttribute{
    *accountIDResourceAttribute, *serviceNameResourceAttribute},
  Tags: []iampolicymanagementv1.ResourceTag{*policyResourceTag},
}

options := iamPolicyManagementService.NewCreatePolicyOptions(
  "access",
  []iampolicymanagementv1.PolicySubject{*policySubjects},
  []iampolicymanagementv1.PolicyRole{*policyRoles},
  []iampolicymanagementv1.PolicyResource{*policyResources},
)

policy, response, err := iamPolicyManagementService.CreatePolicy(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(policy, "", "  ")
fmt.Println(string(b))

Example request

SubjectAttribute subjectAttribute = new SubjectAttribute.Builder()
        .name("iam_id")
        .value(EXAMPLE_USER_ID)
        .build();

PolicySubject policySubjects = new PolicySubject.Builder()
        .addAttributes(subjectAttribute)
        .build();

PolicyRole policyRoles = new PolicyRole.Builder()
        .roleId("crn:v1:bluemix:public:iam::::role:Viewer")
        .build();

ResourceAttribute accountIdResourceAttribute = new ResourceAttribute.Builder()
        .name("accountId")
        .value(exampleAccountId)
        .operator("stringEquals")
        .build();

ResourceAttribute serviceNameResourceAttribute = new ResourceAttribute.Builder()
        .name("serviceType")
        .value("service")
        .operator("stringEquals")
        .build();

ResourceTag policyResourceTag = new ResourceTag.Builder()
        .name("project")
        .value("prototype")
        .operator("stringEquals")
        .build();

PolicyResource policyResources = new PolicyResource.Builder()
        .addAttributes(accountIdResourceAttribute)
        .addAttributes(serviceNameResourceAttribute)
        .addTags(policyResourceTag)
        .build();

CreatePolicyOptions options = new CreatePolicyOptions.Builder()
        .type("access")
        .subjects(Arrays.asList(policySubjects))
        .roles(Arrays.asList(policyRoles))
        .resources(Arrays.asList(policyResources))
        .build();

Response<Policy> response = service.createPolicy(options).execute();
Policy policy = response.getResult();

System.out.println(policy);

Example request

const policySubjects = [
  {
    attributes: [
      {
        name: 'iam_id',
        value: exampleUserId,
      },
    ],
  },
];
const policyRoles = [
  {
    role_id: 'crn:v1:bluemix:public:iam::::role:Viewer',
  },
];
const accountIdResourceAttribute = {
  name: 'accountId',
  value: exampleAccountId,
  operator: 'stringEquals',
};
const serviceNameResourceAttribute = {
  name: 'serviceType',
  value: 'service',
  operator: 'stringEquals',
};
const policyResourceTag = {
  name: 'project',
  operator: 'stringEquals',
  value: 'prototype',
};
const policyResources = [
  {
    attributes: [accountIdResourceAttribute, serviceNameResourceAttribute],
    tags: [policyResourceTag],
  },
];
const params = {
  type: 'access',
  subjects: policySubjects,
  roles: policyRoles,
  resources: policyResources,
};

try {
  const res = await iamPolicyManagementService.createPolicy(params);
  examplePolicyId = res.result.id;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}

Example request

policy_subjects = PolicySubject(attributes=[SubjectAttribute(name='iam_id', value=example_user_id)])
policy_roles = PolicyRole(role_id='crn:v1:bluemix:public:iam::::role:Viewer')
account_id_resource_attribute = ResourceAttribute(name='accountId', value=example_account_id)
service_name_resource_attribute = ResourceAttribute(name='serviceType', value='service')
policy_resource_tag = ResourceTag(name='project', value='prototype')
policy_resources = PolicyResource(
  attributes=[account_id_resource_attribute, service_name_resource_attribute], tags=[policy_resource_tag]
)

policy = iam_policy_management_service.create_policy(
  type='access', subjects=[policy_subjects], roles=[policy_roles], resources=[policy_resources]
).get_result()

print(json.dumps(policy, indent=2))

Response

Response Body

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Status Code

201
Policy creation successful.
400
Policy input is invalid.
401
The token you provided is not valid.
403
You do not have access to create the policy.
406
The requested resource(s) cannot be formatted using the requested media type(s).
409
A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.
415
Request body sent was formatted using an unsupported media type.
422
Exceeded maximum policies quota.
429
Too many requests have been made within a given time window.

Example responses

Status 201

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ],
      "tags": [
        {
          "name": "project",
          "value": "moonshot",
          "operator": "stringEquals"
        },
        {
          "name": "pipeline",
          "value": "test",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Success example

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ],
      "tags": [
        {
          "name": "project",
          "value": "moonshot",
          "operator": "stringEquals"
        },
        {
          "name": "pipeline",
          "value": "test",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Status 400

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "Invalid body format. Check the input parameters."
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "Invalid body format. Check the input parameters."
    }
  ],
  "status_code": 400
}

Status 401

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

Error example

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

Status 403

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to create the requested policy."
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to create the requested policy."
    }
  ],
  "status_code": 403
}

Status 406

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Status 409

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_conflict_error",
      "message": "Failed to create policy.",
      "details": {
        "conflicts_with": {
          "etag": "1-847833cec3bf3f3c3231d8f9492febac",
          "policy": "POLICY"
        }
      },
      "status_code": 409
    }
  ]
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_conflict_error",
      "message": "Failed to create policy.",
      "details": {
        "conflicts_with": {
          "etag": "1-847833cec3bf3f3c3231d8f9492febac",
          "policy": "POLICY"
        }
      },
      "status_code": 409
    }
  ]
}

Status 415

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unsupported_content_type",
      "message": "The supported media type for this API is 'application/json'."
    }
  ],
  "status_code": 415
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unsupported_content_type",
      "message": "The supported media type for this API is 'application/json'."
    }
  ],
  "status_code": 415
}

Status 422

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "request_not_processed",
      "message": "Exceeded maximum policies quota (<limit>) for account <account_id>."
    }
  ],
  "status_code": 422
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "request_not_processed",
      "message": "Exceeded maximum policies quota (<limit>) for account <account_id>."
    }
  ],
  "status_code": 422
}

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy. The policy type cannot be changed (You cannot change an access policy to an authorization policy).

Access

To update an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, or resourceGroupId attribute and the accountId attribute.` If the subject is a locked service-id, the request will fail.

Authorization

To update an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes might support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy. The policy type cannot be changed (You cannot change an access policy to an authorization policy).

Access

To update an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, or resourceGroupId attribute and the accountId attribute.` If the subject is a locked service-id, the request will fail.

Authorization

To update an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes might support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy. The policy type cannot be changed (You cannot change an access policy to an authorization policy).

Access

To update an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, or resourceGroupId attribute and the accountId attribute.` If the subject is a locked service-id, the request will fail.

Authorization

To update an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes might support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy. The policy type cannot be changed (You cannot change an access policy to an authorization policy).

Access

To update an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, or resourceGroupId attribute and the accountId attribute.` If the subject is a locked service-id, the request will fail.

Authorization

To update an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes might support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy. The policy type cannot be changed (You cannot change an access policy to an authorization policy).

Access

To update an access policy, use "type": "access" in the body. The possible subject attributes are iam_id and access_group_id. Use the iam_id subject attribute for assigning access for a user or service-id. Use the access_group_id subject attribute for assigning access for an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the serviceType, serviceName, or resourceGroupId attribute and the accountId attribute.` If the subject is a locked service-id, the request will fail.

Authorization

To update an authorization policy, use "type": "authorization" in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the accountId attributes. The policy subject must include either serviceName or resourceGroupId (or both) attributes.

Attribute Operators

Currently, only the stringEquals and the stringMatch operators are available. Resource attributes might support one or both operators. For more information, see Assigning access by using wildcard policies.

Attribute Validations

Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.

PUT /v1/policies/{policy_id}

(iamPolicyManagement *IamPolicyManagementV1) ReplacePolicy(replacePolicyOptions *ReplacePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

(iamPolicyManagement *IamPolicyManagementV1) ReplacePolicyWithContext(ctx context.Context, replacePolicyOptions *ReplacePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

ServiceCall<Policy> replacePolicy(ReplacePolicyOptions replacePolicyOptions)

replacePolicy(params)

replace_policy(
        self,
        policy_id: str,
        if_match: str,
        type: str,
        subjects: List['PolicySubject'],
        roles: List['PolicyRole'],
        resources: List['PolicyResource'],
        *,
        description: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam.policy.update

Auditing

Calling this method generates the following auditing event.

iam-am.policy.update

Request

Instantiate the ReplacePolicyOptions struct and set the fields to provide parameter values for the ReplacePolicy method.

Use the ReplacePolicyOptions.Builder to create a ReplacePolicyOptions object that contains the parameter values for the replacePolicy method.

Custom Headers

If-Match
Required*
string
The revision number for updating a policy and must match the ETag value of the existing policy. The Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.

Path Parameters

policy_id
Required*
string
The policy ID.

Request Body

Required*

PolicyRequest

Updated policy content to be saved.

parameter

WithContext method only

ReplacePolicyOptions

The ReplacePolicy options.

ReplacePolicyOptions

The replacePolicy options.

parameters

policyId
Required*
string
The policy ID.
ifMatch
Required*
string
The revision number for updating a policy and must match the ETag value of the existing policy. The Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.
type
Required*
string
The policy type; either 'access' or 'authorization'.

Possible values: 6 ≤ length ≤ 13, Value must match regular expression /^[a-z]+$/
subjects
Required*
The subjects associated with a policy.

Possible values: number of items = 1
roles
Required*
A set of role cloud resource names (CRNs) granted by the policy.

Possible values: number of items ≥ 1
resources
Required*
The resources associated with a policy.

Possible values: number of items = 1
description
string
Customer-defined description.

Possible values: 1 ≤ length ≤ 300

parameters

policy_id
Required*
str
The policy ID.
if_match
Required*
str
The revision number for updating a policy and must match the ETag value of the existing policy. The Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.
type
Required*
str
The policy type; either 'access' or 'authorization'.

Possible values: 6 ≤ length ≤ 13, Value must match regular expression /^[a-z]+$/
subjects
Required*
The subjects associated with a policy.

Possible values: number of items = 1
roles
Required*
A set of role cloud resource names (CRNs) granted by the policy.

Possible values: number of items ≥ 1
resources
Required*
The resources associated with a policy.

Possible values: number of items = 1
description
str
Customer-defined description.

Possible values: 1 ≤ length ≤ 300

Example request

curl -X PUT 'https://iam.cloud.ibm.com/v1/policies' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -H 'If-Match: $ETAG' -d '{
  "type": "access",
  "description": "Viewer role for for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }'
  ],
  "roles":[
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources":[
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "$ACCOUNT_ID"
        },
        {
          "name": "serviceName",
          "value": "$SERVICE_NAME"
        }
      ]
    }
  ]
}'

Example request

subjectAttribute := &iampolicymanagementv1.SubjectAttribute{
  Name:  core.StringPtr("iam_id"),
  Value: &exampleUserID,
}
policySubjects := &iampolicymanagementv1.PolicySubject{
  Attributes: []iampolicymanagementv1.SubjectAttribute{*subjectAttribute},
}
accountIDResourceAttribute := &iampolicymanagementv1.ResourceAttribute{
  Name:     core.StringPtr("accountId"),
  Value:    core.StringPtr(exampleAccountID),
  Operator: core.StringPtr("stringEquals"),
}
serviceNameResourceAttribute := &iampolicymanagementv1.ResourceAttribute{
  Name:     core.StringPtr("serviceType"),
  Value:    core.StringPtr("service"),
  Operator: core.StringPtr("stringEquals"),
}
policyResourceTag := &iampolicymanagementv1.ResourceTag{
  Name:     core.StringPtr("project"),
  Value:    core.StringPtr("prototype"),
  Operator: core.StringPtr("stringEquals"),
}
policyResources := &iampolicymanagementv1.PolicyResource{
  Attributes: []iampolicymanagementv1.ResourceAttribute{
    *accountIDResourceAttribute, *serviceNameResourceAttribute},
  Tags: []iampolicymanagementv1.ResourceTag{*policyResourceTag},
}
updatedPolicyRoles := &iampolicymanagementv1.PolicyRole{
  RoleID: core.StringPtr("crn:v1:bluemix:public:iam::::role:Editor"),
}

options := iamPolicyManagementService.NewReplacePolicyOptions(
  examplePolicyID,
  examplePolicyETag,
  "access",
  []iampolicymanagementv1.PolicySubject{*policySubjects},
  []iampolicymanagementv1.PolicyRole{*updatedPolicyRoles},
  []iampolicymanagementv1.PolicyResource{*policyResources},
)

policy, response, err := iamPolicyManagementService.ReplacePolicy(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(policy, "", "  ")
fmt.Println(string(b))

Example request

SubjectAttribute subjectAttribute = new SubjectAttribute.Builder()
        .name("iam_id")
        .value(EXAMPLE_USER_ID)
        .build();

PolicySubject policySubjects = new PolicySubject.Builder()
        .addAttributes(subjectAttribute)
        .build();

ResourceAttribute accountIdResourceAttribute = new ResourceAttribute.Builder()
        .name("accountId")
        .value(exampleAccountId)
        .operator("stringEquals")
        .build();

ResourceAttribute serviceNameResourceAttribute = new ResourceAttribute.Builder()
        .name("serviceType")
        .value("service")
        .operator("stringEquals")
        .build();

ResourceTag policyResourceTag = new ResourceTag.Builder()
        .name("project")
        .value("prototype")
        .operator("stringEquals")
        .build();

PolicyResource policyResources = new PolicyResource.Builder()
        .addAttributes(accountIdResourceAttribute)
        .addAttributes(serviceNameResourceAttribute)
        .addTags(policyResourceTag)
        .build();

PolicyRole updatedPolicyRole = new PolicyRole.Builder()
        .roleId("crn:v1:bluemix:public:iam::::role:Editor")
        .build();

ReplacePolicyOptions options = new ReplacePolicyOptions.Builder()
        .type("access")
        .policyId(examplePolicyId)
        .ifMatch(examplePolicyEtag)
        .subjects(new ArrayList<PolicySubject>(Arrays.asList(policySubjects)))
        .roles(new ArrayList<PolicyRole>(Arrays.asList(updatedPolicyRole)))
        .resources(new ArrayList<PolicyResource>(Arrays.asList(policyResources)))
        .build();

Response<Policy> response = service.replacePolicy(options).execute();
Policy policy = response.getResult();

System.out.println(policy);

Example request

const policySubjects = [
  {
    attributes: [
      {
        name: 'iam_id',
        value: exampleUserId,
      },
    ],
  },
];
const accountIdResourceAttribute = {
  name: 'accountId',
  value: exampleAccountId,
  operator: 'stringEquals',
};
const serviceNameResourceAttribute = {
  name: 'serviceType',
  value: 'service',
  operator: 'stringEquals',
};
const policyResourceTag = {
  name: 'project',
  operator: 'stringEquals',
  value: 'prototype',
};
const policyResources = [
  {
    attributes: [accountIdResourceAttribute, serviceNameResourceAttribute],
    tags: [policyResourceTag],
  },
];
const updatedPolicyRoles = [
  {
    role_id: 'crn:v1:bluemix:public:iam::::role:Editor',
  },
];
const params = {
  type: 'access',
  policyId: examplePolicyId,
  ifMatch: examplePolicyETag,
  subjects: policySubjects,
  roles: updatedPolicyRoles,
  resources: policyResources,
};

try {
  const res = await iamPolicyManagementService.replacePolicy(params);
  examplePolicyETag = res.headers.etag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}

Example request

policy_subjects = PolicySubject(attributes=[SubjectAttribute(name='iam_id', value=example_user_id)])
account_id_resource_attribute = ResourceAttribute(name='accountId', value=example_account_id)
service_name_resource_attribute = ResourceAttribute(name='serviceType', value='service')
policy_resource_tag = ResourceTag(name='project', value='prototype')
policy_resources = PolicyResource(
  attributes=[account_id_resource_attribute, service_name_resource_attribute], tags=[policy_resource_tag]
)
updated_policy_roles = PolicyRole(role_id='crn:v1:bluemix:public:iam::::role:Editor')

response = iam_policy_management_service.replace_policy(
  type='access',
  policy_id=example_policy_id,
  if_match=example_policy_etag,
  subjects=[policy_subjects],
  roles=[updated_policy_roles],
  resources=[policy_resources],
)
policy = response.get_result()

print(json.dumps(policy, indent=2))

Response

Response Body

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Status Code

200
Policy update successful.
400
Policy input is invalid.
401
The token you provided is not valid.
403
You do not have access to update the policy.
404
Policy was not found.
406
The requested resource(s) cannot be formatted using the requested media type(s).
409
A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.
415
Request body sent was formatted using an unsupported media type.
429
Too many requests have been made within a given time window.

Example responses

Status 200

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Success example

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Status 400

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "A policy's type cannot be updated. Create a new policy and delete the existing one."
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "A policy's type cannot be updated. Create a new policy and delete the existing one."
    }
  ],
  "status_code": 400
}

Status 401

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

Error example

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

Status 403

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to update the requested policy."
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to update the requested policy."
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_not_found",
      "message": "Policy with Id POLICY_ID not found."
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_not_found",
      "message": "Policy with Id POLICY_ID not found."
    }
  ],
  "status_code": 404
}

Status 406

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Status 409

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_conflict_error",
      "message": "Failed to update policy.",
      "details": {
        "conflicts_with": {
          "etag": "1-847833cec3bf3f3c3231d8f9492febac",
          "policy": "POLICY"
        }
      },
      "status_code": 409
    }
  ]
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_conflict_error",
      "message": "Failed to update policy.",
      "details": {
        "conflicts_with": {
          "etag": "1-847833cec3bf3f3c3231d8f9492febac",
          "policy": "POLICY"
        }
      },
      "status_code": 409
    }
  ]
}

Status 415

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unsupported_content_type",
      "message": "The supported media type for this API is 'application/json'."
    }
  ],
  "status_code": 415
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unsupported_content_type",
      "message": "The supported media type for this API is 'application/json'."
    }
  ],
  "status_code": 415
}

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Retrieve a policy by providing a policy ID.

GET /v1/policies/{policy_id}

(iamPolicyManagement *IamPolicyManagementV1) GetPolicy(getPolicyOptions *GetPolicyOptions) (result *PolicyTemplateMetaData, response *core.DetailedResponse, err error)

(iamPolicyManagement *IamPolicyManagementV1) GetPolicyWithContext(ctx context.Context, getPolicyOptions *GetPolicyOptions) (result *PolicyTemplateMetaData, response *core.DetailedResponse, err error)

ServiceCall<PolicyTemplateMetaData> getPolicy(GetPolicyOptions getPolicyOptions)

getPolicy(params)

get_policy(
        self,
        policy_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam.policy.read

Auditing

Calling this method generates the following auditing event.

iam-am.policy.read

Request

Instantiate the GetPolicyOptions struct and set the fields to provide parameter values for the GetPolicy method.

Use the GetPolicyOptions.Builder to create a GetPolicyOptions object that contains the parameter values for the getPolicy method.

Path Parameters

policy_id
Required*
string
The policy ID.

parameter

WithContext method only

GetPolicyOptions

The GetPolicy options.

GetPolicyOptions

The getPolicy options.

parameters

policyId
Required*
string
The policy ID.

parameters

policy_id
Required*
str
The policy ID.

Example request

curl -X GET 'https://iam.cloud.ibm.com/v1/policies/$POLICY_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

Example request

options := iamPolicyManagementService.NewGetPolicyOptions(
  examplePolicyID,
)

policy, response, err := iamPolicyManagementService.GetPolicy(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(policy, "", "  ")
fmt.Println(string(b))

Example request

GetPolicyOptions options = new GetPolicyOptions.Builder()
        .policyId(examplePolicyId)
        .build();

Response<Policy> response = service.getPolicy(options).execute();
Policy policy = response.getResult();

System.out.println(policy);

Example request

const params = {
  policyId: examplePolicyId,
};

try {
  const res = await iamPolicyManagementService.getPolicy(params);
  examplePolicyETag = res.headers.etag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}

Example request

response = iam_policy_management_service.get_policy(policy_id=example_policy_id)
policy = response.get_result()

print(json.dumps(policy, indent=2))

Response

Response Body

PolicyTemplateMetaData

The core set of properties associated with a policy.

PolicyTemplateMetaData

The core set of properties associated with a policy.

PolicyTemplateMetaData

The core set of properties associated with a policy.

PolicyTemplateMetaData

The core set of properties associated with a policy.

PolicyTemplateMetaData

The core set of properties associated with a policy.

Status Code

200
Policy retrieval successful.
401
The token you provided is not valid.
403
You do not have access to retrieve the policy.
404
Policy was not found.
406
The requested resource(s) cannot be formatted using the requested media type(s).
429
Too many requests have been made within a given time window.

Example responses

Status 200

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Success example

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Status 401

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

Error example

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

Status 403

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to retrieve the requested policy."
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to retrieve the requested policy."
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_not_found",
      "message": "Policy with Id POLICY_ID not found."
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_not_found",
      "message": "Policy with Id POLICY_ID not found."
    }
  ],
  "status_code": 404
}

Status 406

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "unable_to_process",
      "message": "The requested resource(s) can only be formatted using the 'application/json' media type."
    }
  ],
  "status_code": 406
}

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Delete a policy by providing a policy ID. A policy cannot be deleted if the subject ID contains a locked service ID. If the subject of the policy is a locked service-id, the request will fail.

DELETE /v1/policies/{policy_id}

(iamPolicyManagement *IamPolicyManagementV1) DeletePolicy(deletePolicyOptions *DeletePolicyOptions) (response *core.DetailedResponse, err error)

(iamPolicyManagement *IamPolicyManagementV1) DeletePolicyWithContext(ctx context.Context, deletePolicyOptions *DeletePolicyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deletePolicy(DeletePolicyOptions deletePolicyOptions)

deletePolicy(params)

delete_policy(
        self,
        policy_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam.policy.delete

Auditing

Calling this method generates the following auditing event.

iam-am.policy.delete

Request

Instantiate the DeletePolicyOptions struct and set the fields to provide parameter values for the DeletePolicy method.

Use the DeletePolicyOptions.Builder to create a DeletePolicyOptions object that contains the parameter values for the deletePolicy method.

Path Parameters

policy_id
Required*
string
The policy ID.

parameter

WithContext method only

DeletePolicyOptions

The DeletePolicy options.

DeletePolicyOptions

The deletePolicy options.

parameters

policyId
Required*
string
The policy ID.

parameters

policy_id
Required*
str
The policy ID.

Example request

curl -X DELETE 'https://iam.cloud.ibm.com/v1/policies/$POLICY_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

Example request

options := iamPolicyManagementService.NewDeletePolicyOptions(
  examplePolicyID,
)

response, err := iamPolicyManagementService.DeletePolicy(options)
if err != nil {
  panic(err)
}

Example request

DeletePolicyOptions options = new DeletePolicyOptions.Builder()
        .policyId(examplePolicyId)
        .build();

Response<Void> response = service.deletePolicy(options).execute();

Example request

const params = {
  policyId: examplePolicyId,
};

try {
  await iamPolicyManagementService.deletePolicy(params);
} catch (err) {
  console.warn(err);
}

Example request

response = iam_policy_management_service.delete_policy(policy_id=example_policy_id).get_result()

print(json.dumps(response, indent=2))

Response

Status Code

204
Policy deletion successful.
400
Policy was not valid to delete.
401
The token you provided is not valid.
403
You do not have access to delete the policy.
404
Policy was not found.
429
Too many requests have been made within a given time window.

Example responses

Status 400

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "Request includes a locked service id, cannot perform action"
    }
  ],
  "status_code": 400
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "Request includes a locked service id, cannot perform action"
    }
  ],
  "status_code": 400
}

Status 401

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

Error example

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

Status 403

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to delete the requested policy."
    }
  ],
  "status_code": 403
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "insufficent_permissions",
      "message": "You are not allowed to delete the requested policy."
    }
  ],
  "status_code": 403
}

Status 404

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_not_found",
      "message": "Policy with Id POLICY_ID not found."
    }
  ],
  "status_code": 404
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "policy_not_found",
      "message": "Policy with Id POLICY_ID not found."
    }
  ],
  "status_code": 404
}

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Error example

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}

Restore a policy that has recently been deleted. A policy administrator might want to restore a deleted policy. To restore a policy, use "state": "active" in the body.

PATCH /v1/policies/{policy_id}

(iamPolicyManagement *IamPolicyManagementV1) UpdatePolicyState(updatePolicyStateOptions *UpdatePolicyStateOptions) (result *Policy, response *core.DetailedResponse, err error)

(iamPolicyManagement *IamPolicyManagementV1) UpdatePolicyStateWithContext(ctx context.Context, updatePolicyStateOptions *UpdatePolicyStateOptions) (result *Policy, response *core.DetailedResponse, err error)

ServiceCall<Policy> updatePolicyState(UpdatePolicyStateOptions updatePolicyStateOptions)

updatePolicyState(params)

update_policy_state(
        self,
        policy_id: str,
        if_match: str,
        *,
        state: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

iam.policy.create

Auditing

Calling this method generates the following auditing event.

iam-am.policy.update

Request

Instantiate the UpdatePolicyStateOptions struct and set the fields to provide parameter values for the UpdatePolicyState method.

Use the UpdatePolicyStateOptions.Builder to create a UpdatePolicyStateOptions object that contains the parameter values for the updatePolicyState method.

Custom Headers

If-Match
Required*
string
The revision number for updating a policy and must match the ETag value of the existing policy. The Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.

Path Parameters

policy_id
Required*
string
The policy ID.

Request Body

Required*

PatchPolicyRequest

Policy attribute to be updated.

parameter

WithContext method only

UpdatePolicyStateOptions

The UpdatePolicyState options.

UpdatePolicyStateOptions

The updatePolicyState options.

parameters

policyId
Required*
string
The policy ID.
ifMatch
Required*
string
The revision number for updating a policy and must match the ETag value of the existing policy. The Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.
state
string
The policy state.

Allowable values: [active,deleted]

parameters

policy_id
Required*
str
The policy ID.
if_match
Required*
str
The revision number for updating a policy and must match the ETag value of the existing policy. The Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.
state
str
The policy state.

Allowable values: [active,deleted]

Example request

curl -X PATCH 'https://iam.cloud.ibm.com/v1/policies' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -H 'If-Match: $ETAG' -d '{
  "state": "active",
}'

Example request

options := iamPolicyManagementService.NewUpdatePolicyStateOptions(
  examplePolicyID,
  examplePolicyETag,
)

options.SetState("active")

policy, response, err := iamPolicyManagementService.UpdatePolicyState(options)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(policy, "", "  ")
fmt.Println(string(b))

Example request

UpdatePolicyStateOptions updatePolicyStateOptions = new UpdatePolicyStateOptions.Builder()
        .policyId(examplePolicyId)
        .ifMatch(examplePolicyEtag)
        .state("active")
        .build();

Response<Policy> response = service.updatePolicyState(updatePolicyStateOptions).execute();
Policy policy = response.getResult();

System.out.println(policy);

Example request

const params = {
  policyId: examplePolicyId,
  ifMatch: examplePolicyETag,
  state: 'active'
};

try {
  const res = await iamPolicyManagementService.updatePolicyState(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}

Example request

policy = iam_policy_management_service.update_policy_state(
  policy_id=example_policy_id, if_match=example_updated_policy_etag, state='active'
).get_result()

print(json.dumps(policy, indent=2))

Response

Response Body

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Policy

The core set of properties associated with a policy.

Status Code

200
Policy successfully restored.
400
Policy input is invalid.
401
The token you provided is not valid.
403
You do not have access to update the policy.
404
Policy was not found.
406
The requested resource(s) cannot be formatted using the requested media type(s).
415
Request body sent was formatted using an unsupported media type.
429
Too many requests have been made within a given time window.

Example responses

Status 200

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Success example

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "description": "Viewer role access for all instances of SERVICE_NAME in the account.",
  "subjects": [
    {
      "attributes": [
        {
          "name": "iam_id",
          "value": "IBMid-123453user"
        }
      ]
    }
  ],
  "roles": [
    {
      "role_id": "crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "resources": [
    {
      "attributes": [
        {
          "name": "accountId",
          "value": "ACCOUNT_ID",
          "operator": "stringEquals"
        },
        {
          "name": "serviceName",
          "value": "SERVICE_NAME",
          "operator": "stringEquals"
        }
      ]
    }
  ],
  "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab",
  "created_at": "2018-08-30T14:09:09.907Z",
  "created_by_id": "USER_ID",
  "last_modified_at": "2018-08-30T14:09:09.907Z",
  "last_modified_by_id": "USER_ID",
  "state": "active"
}

Status 400

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "Invalid body format. Check missing parameters."
    }
  ],
  "status_code": 400
}

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Additional headers

Transaction-Id

Sorting

Policy data enrichment

Rate limiting

Related APIs

Methods

Get policies by attributes

Authorization

Auditing

Request

Custom Headers

Accept-Language

Query Parameters

account_id

iam_id

access_group_id

type

service_type

tag_name

tag_value

sort

format

state

parameter

ctx

ListPoliciesOptions

AccountID

AcceptLanguage

IamID

AccessGroupID

Type

ServiceType

TagName

TagValue

Sort

Format

State

ListPoliciesOptions

accountId

acceptLanguage

iamId

accessGroupId

type

serviceType

tagName

tagValue

sort

format

state

parameters

accountId

acceptLanguage

iamId

accessGroupId

type

serviceType

tagName

tagValue

sort

format

state

parameters

account_id

accept_language

iam_id

access_group_id

type

service_type

tag_name

tag_value

sort

format

state

Response