Introduction
With the IBM Cloud® Identity and Access Management (IAM) Policy Management API, you can create, update, view, and delete IAM policies. An IAM policy enables a subject to access a resource. These policies are used in access decisions when you call APIs for IAM-enabled services. For more information about how access management works, see Managing access in IBM Cloud.
There are three primary values in a policy: a subject, roles, and resources.
The subject is who or what is being granted access. The subject can be an IAM ID or an access group ID. The IAM ID is the ID of the entity that you are giving access to. The value can be a user or a service ID. The access group ID is the ID of the access group. An access group contains a set of users or service IDs. Access groups are the preferred method of managing access control. For more information, see Setting up access groups.
The following table shows the example formats for the supported subject types:
Type | Attribute name | Attribute value | |
---|---|---|---|
User | iam_id | IBMid-123456... |
|
Service ID | iam_id | iam-ServiceId-12345... |
|
Access group | access_group_id | AccessGroupId-12345... |
The second value in a policy in the role. A role is a collection of actions that can be taken on a resource. There are platform, service, and custom roles. For more information, see IAM roles. And, the final value of the policy is the targeted resources whether it's an entire service, resource group, or specific service instance.
Two types of policies are supported: access policies and authorization policies. For more information, see Create a policy.
Example API request
curl -X {request_method} "https://iam.cloud.ibm.com/{method_endpoint}"
Replace {request_method}
and {method_endpoint}
in this example with the values for your particular API call.
The code examples on this tab use the client library that is provided for Go.
Installation
go get -u github.com/IBM/platform-services-go-sdk
GitHub
The code examples on this tab use the client library that is provided for Java.
Installation
Maven:
<dependency>
<groupId>com.ibm.cloud</groupId>
<artifactId>platform-services</artifactId>
<version>X.X.X</version>
</dependency>
Gradle:
compile 'com.ibm.cloud:platform-services:X.X.X'
GitHub
The code examples on this tab use the client library that is provided for Node.js.
Installation
npm install ibm-platform-services
GitHub
The code examples on this tab use the client library that is provided for Python.
Installation
pip install --upgrade "ibm_platform_services>=X.X.X"
GitHub
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
- Dallas:
Example API request
curl -X {request_method} "https://private.iam.{DomainName}/{method_endpoint}"
Replace {request_method}
and {method_endpoint}
in the example with the values for your particular API call.
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. |
Authentication
Authorization to the IAM Policy Management API is enforced by using an IAM access token. The token is used to validate the identity of the caller and verify access to IAM API services. Obtaining an IAM Token for an authenticated User or Service ID is captured in the IAM Identity Service documentation.
Use of the IAM Policy Management REST API is done by adding a valid IAM Token to the HTTP Authorization
request header. Example: -H 'Authorization: Bearer $TOKEN'
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.
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.
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.
Methods
Get policies by attributes
Get policies and filter by attributes. While managing policies, you may want to retrieve policies in the account and filter by attribute values. This can be done through query parameters. Currently, only 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 policies and filter by attributes. While managing policies, you may want to retrieve policies in the account and filter by attribute values. This can be done through query parameters. Currently, only 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 policies and filter by attributes. While managing policies, you may want to retrieve policies in the account and filter by attribute values. This can be done through query parameters. Currently, only 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 policies and filter by attributes. While managing policies, you may want to retrieve policies in the account and filter by attribute values. This can be done through query parameters. Currently, only 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 policies and filter by attributes. While managing policies, you may want to retrieve policies in the account and filter by attribute values. This can be done through query parameters. Currently, only 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 *PolicyList, response *core.DetailedResponse, err error)
(iamPolicyManagement *IamPolicyManagementV1) ListPoliciesWithContext(ctx context.Context, listPoliciesOptions *ListPoliciesOptions) (result *PolicyList, response *core.DetailedResponse, err error)
ServiceCall<PolicyList> 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
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
Translation language code
Query Parameters
The account GUID in which the policies belong to.
The IAM ID used to identify the subject.
The access group id.
The type of policy (access or authorization).
The type of service.
The name of the access management tag in the policy.
The value of the access management tag in the policy.
Sort the results by any of the top level policy fields (id, created_at, created_by_id, last_modified_at, etc).
Include additional data per policy returned [include_last_permit, display].
The state of the policy, 'active' or 'deleted'.
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The ListPolicies options.
The account GUID in which the policies belong to.
Translation language code.
The IAM ID used to identify the subject.
The access group id.
The type of policy (access or authorization).
The type of service.
The name of the access management tag in the policy.
The value of the access management tag in the policy.
Sort the results by any of the top level policy fields (id, created_at, created_by_id, last_modified_at, etc).
Include additional data per policy returned [include_last_permit, display].
The state of the policy, 'active' or 'deleted'.
The listPolicies options.
The account GUID in which the policies belong to.
Translation language code.
The IAM ID used to identify the subject.
The access group id.
The type of policy (access or authorization).
The type of service.
The name of the access management tag in the policy.
The value of the access management tag in the policy.
Sort the results by any of the top level policy fields (id, created_at, created_by_id, last_modified_at, etc).
Include additional data per policy returned [include_last_permit, display].
The state of the policy, 'active' or 'deleted'.
parameters
The account GUID in which the policies belong to.
Translation language code.
The IAM ID used to identify the subject.
The access group id.
The type of policy (access or authorization).
The type of service.
The name of the access management tag in the policy.
The value of the access management tag in the policy.
Sort the results by any of the top level policy fields (id, created_at, created_by_id, last_modified_at, etc).
Include additional data per policy returned [include_last_permit, display].
The state of the policy, 'active' or 'deleted'.
parameters
The account GUID in which the policies belong to.
Translation language code.
The IAM ID used to identify the subject.
The access group id.
The type of policy (access or authorization).
The type of service.
The name of the access management tag in the policy.
The value of the access management tag in the policy.
Sort the results by any of the top level policy fields (id, created_at, created_by_id, last_modified_at, etc).
Include additional data per policy returned [include_last_permit, display].
The state of the policy, 'active' or 'deleted'.
curl -X GET 'https://iam.cloud.ibm.com/v1/policies?account_id=$ACCOUNT_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'
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))
ListPoliciesOptions options = new ListPoliciesOptions.Builder() .accountId(exampleAccountId) .iamId(EXAMPLE_USER_ID) .format("include_last_permit") .build(); Response<PolicyList> response = service.listPolicies(options).execute(); PolicyList policyList = response.getResult(); System.out.println(policyList);
const params = { accountId: exampleAccountId, iamId: exampleUserId, format: 'include_last_permit', }; iamPolicyManagementService.listPolicies(params) .then(res => { console.log('listPolicies() result:\n' + JSON.stringify(res.result, null, 2)); }) .catch(err => { console.warn(err) });
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
A collection of policies.
List of policies.
A collection of policies.
List of policies.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
Policies
A collection of policies.
List of policies.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
policies
A collection of policies.
List of policies.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
policies
A collection of policies.
List of policies.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
policies
Status Code
Policies retrieval successful.
The request you made is not valid.
The token you provided is not valid.
The requested resource(s) cannot be formatted using the requested media type(s).
Too many requests have been made within a given time window.
{ "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": [ { "roles_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" } ] }
{ "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": [ { "roles_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" } ] }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "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 }
{ "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 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
Create a policy
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.
The roles must be a subset of a service's or the platform's supported roles.
The resource attributes must be a subset of a service's or the platform's supported attributes.
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
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
The policy roles must be a subset of the supported authorization roles supported by the target service.
The user must also have the same level of access or greater to the target resource in order to grant the role.
The resource attributes must be a subset of a service's or the platform's supported attributes.
Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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
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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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
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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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
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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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
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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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
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
Translation language code
A policy to be created.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The resources associated with a policy.
Constraints: number of items ≤ 1
Customer-defined description
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The CreatePolicy options.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
Customer-defined description.
Translation language code.
The createPolicy options.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
Customer-defined description.
Translation language code.
parameters
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
Customer-defined description.
Translation language code.
parameters
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
Customer-defined description.
Translation language code.
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" } ] } ] }'
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))
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);
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, }; iamPolicyManagementService.createPolicy(params) .then(res => { examplePolicyId = res.result.id; console.log('createPolicy() result:\n' + JSON.stringify(res.result, null, 2)); }) .catch(err => { console.warn(err) });
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
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description
The subjects associated with a policy.
Constraints: number of items = 1
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The resources associated with a policy.
Constraints: number of items ≤ 1
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
Status Code
Policy creation successful.
Policy input is invalid.
The token you provided is not valid.
You do not have access to create the policy.
The requested resource(s) cannot be formatted using the requested media type(s).
A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.
Request body sent was formatted using an unsupported media type.
Exceeded maximum policies quota.
Too many requests have been made within a given time window.
{ "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": [ { "roles_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" }
{ "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": [ { "roles_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" }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "The following role(s) had multiple entries: crn:v1:bluemix:public:iam::::role:Viewer" } ], "status_code": 400 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "The following role(s) had multiple entries: crn:v1:bluemix:public:iam::::role:Viewer" } ], "status_code": 400 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy." } ], "status_code": 403 }
{ "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 }
{ "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 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to create policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to create policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "unsupported_content_type", "message": "The supported media type for this API is 'application/json'." } ], "status_code": 415 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "unsupported_content_type", "message": "The supported media type for this API is 'application/json'." } ], "status_code": 415 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum policies quota (<limit>) for account <account_id>." } ], "status_code": 422 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum policies quota (<limit>) for account <account_id>." } ], "status_code": 422 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
Update a policy
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.
The roles must be a subset of a service's or the platform's supported roles.
The resource attributes must be a subset of a service's or the platform's supported attributes.
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
The policy roles must be a subset of the supported authorization roles supported by the target service.
The user must also have the same level of access or greater to the target resource in order to grant the role.
The resource attributes must be a subset of a service's or the platform's supported attributes.
Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
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. The roles must be a subset of a service's or the platform's supported roles. The resource attributes must be a subset of a service's or the platform's supported attributes. 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 The policy roles must be a subset of the supported authorization roles supported by the target service. The user must also have the same level of access or greater to the target resource in order to grant the role. The resource attributes must be a subset of a service's or the platform's supported attributes. Both the policy subject and the policy resource must include the serviceName
and accountId
attributes.
PUT /v1/policies/{policy_id}
(iamPolicyManagement *IamPolicyManagementV1) UpdatePolicy(updatePolicyOptions *UpdatePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)
(iamPolicyManagement *IamPolicyManagementV1) UpdatePolicyWithContext(ctx context.Context, updatePolicyOptions *UpdatePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)
ServiceCall<Policy> updatePolicy(UpdatePolicyOptions updatePolicyOptions)
updatePolicy(params)
update_policy(self,
policy_id: str,
if_match: str,
type: str,
subjects: List['PolicySubject'],
roles: List['PolicyRole'],
resources: List['PolicyResource'],
*,
description: str = None,
**kwargs
) -> DetailedResponse
Auditing
Calling this method generates the following auditing event.
iam-am.policy.update
Request
Instantiate the UpdatePolicyOptions
struct and set the fields to provide parameter values for the UpdatePolicy
method.
Use the UpdatePolicyOptions.Builder
to create a UpdatePolicyOptions
object that contains the parameter values for the updatePolicy
method.
Custom Headers
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
The policy ID.
Updated policy content to be saved.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The resources associated with a policy.
Constraints: number of items ≤ 1
Customer-defined description
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The UpdatePolicy options.
The policy ID.
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.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
Customer-defined description.
The updatePolicy options.
The policy ID.
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.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
Customer-defined description.
parameters
The policy ID.
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.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
Customer-defined description.
parameters
The policy ID.
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.
The policy type; either 'access' or 'authorization'.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
Customer-defined description.
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" } ] } ] }'
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.NewUpdatePolicyOptions( examplePolicyID, examplePolicyETag, "access", []iampolicymanagementv1.PolicySubject{*policySubjects}, []iampolicymanagementv1.PolicyRole{*updatedPolicyRoles}, []iampolicymanagementv1.PolicyResource{*policyResources}, ) policy, response, err := iamPolicyManagementService.UpdatePolicy(options) if err != nil { panic(err) } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b))
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(); UpdatePolicyOptions options = new UpdatePolicyOptions.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.updatePolicy(options).execute(); Policy policy = response.getResult(); System.out.println(policy);
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, }; iamPolicyManagementService.updatePolicy(params) .then(res => { examplePolicyETag = res.headers.etag; console.log('updatePolicy() result:\n' + JSON.stringify(res.result, null, 2)); }) .catch(err => { console.warn(err) });
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.update_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
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description
The subjects associated with a policy.
Constraints: number of items = 1
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The resources associated with a policy.
Constraints: number of items ≤ 1
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
Status Code
Policy update successful.
Policy input is invalid.
The token you provided is not valid.
You do not have access to update the policy.
Policy was not found.
The requested resource(s) cannot be formatted using the requested media type(s).
A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.
Request body sent was formatted using an unsupported media type.
Too many requests have been made within a given time window.
{ "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": [ { "roles_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" }
{ "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": [ { "roles_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" }
{ "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 }
{ "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 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 }
{ "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 }
{ "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 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to update policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to update policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "unsupported_content_type", "message": "The supported media type for this API is 'application/json'." } ], "status_code": 415 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "unsupported_content_type", "message": "The supported media type for this API is 'application/json'." } ], "status_code": 415 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
Retrieve a policy by ID
Retrieve a policy by providing a policy ID.
Retrieve a policy by providing a policy ID.
Retrieve a policy by providing a policy ID.
Retrieve a policy by providing a policy ID.
Retrieve a policy by providing a policy ID.
GET /v1/policies/{policy_id}
(iamPolicyManagement *IamPolicyManagementV1) GetPolicy(getPolicyOptions *GetPolicyOptions) (result *Policy, response *core.DetailedResponse, err error)
(iamPolicyManagement *IamPolicyManagementV1) GetPolicyWithContext(ctx context.Context, getPolicyOptions *GetPolicyOptions) (result *Policy, response *core.DetailedResponse, err error)
ServiceCall<Policy> getPolicy(GetPolicyOptions getPolicyOptions)
getPolicy(params)
get_policy(self,
policy_id: str,
**kwargs
) -> DetailedResponse
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
The policy ID.
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The GetPolicy options.
The policy ID.
The getPolicy options.
The policy ID.
parameters
The policy ID.
parameters
The policy ID.
curl -X GET 'https://iam.cloud.ibm.com/v1/policies/$POLICY_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'
options := iamPolicyManagementService.NewGetPolicyOptions( examplePolicyID, ) policy, response, err := iamPolicyManagementService.GetPolicy(options) if err != nil { panic(err) } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b))
GetPolicyOptions options = new GetPolicyOptions.Builder() .policyId(examplePolicyId) .build(); Response<Policy> response = service.getPolicy(options).execute(); Policy policy = response.getResult(); System.out.println(policy);
const params = { policyId: examplePolicyId, }; iamPolicyManagementService.getPolicy(params) .then(res => { examplePolicyETag = res.headers.etag; console.log('getPolicy() result:\n' + JSON.stringify(res.result, null, 2)); }) .catch(err => { console.warn(err) });
response = iam_policy_management_service.get_policy( policy_id=example_policy_id ) policy = response.get_result() print(json.dumps(policy, indent=2))
Response
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description
The subjects associated with a policy.
Constraints: number of items = 1
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The resources associated with a policy.
Constraints: number of items ≤ 1
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
Status Code
Policy retrieval successful.
The token you provided is not valid.
You do not have access to retrieve the policy.
Policy was not found.
The requested resource(s) cannot be formatted using the requested media type(s).
Too many requests have been made within a given time window.
{ "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": [ { "roles_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" }
{ "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": [ { "roles_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" }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 }
{ "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 }
{ "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 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
Delete a policy by ID
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 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 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 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 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
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
The policy ID.
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The DeletePolicy options.
The policy ID.
The deletePolicy options.
The policy ID.
parameters
The policy ID.
parameters
The policy ID.
curl -X DELETE 'https://iam.cloud.ibm.com/v1/policies/$POLICY_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'
options := iamPolicyManagementService.NewDeletePolicyOptions( examplePolicyID, ) response, err := iamPolicyManagementService.DeletePolicy(options) if err != nil { panic(err) }
DeletePolicyOptions options = new DeletePolicyOptions.Builder() .policyId(examplePolicyId) .build(); service.deletePolicy(options).execute();
const params = { policyId: examplePolicyId, }; iamPolicyManagementService.deletePolicy(params) .then(res => { console.log('deletePolicy() response status code: ' + res.status); }) .catch(err => { console.warn(err) });
response = iam_policy_management_service.delete_policy( policy_id=example_policy_id ).get_result() print(json.dumps(response, indent=2))
Response
Status Code
Policy deletion successful.
Policy was not valid to delete.
The token you provided is not valid.
You do not have access to delete the policy.
Policy was not found.
Too many requests have been made within a given time window.
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a locked service id, cannot perform action" } ], "status_code": 400 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a locked service id, cannot perform action" } ], "status_code": 400 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy." } ], "status_code": 403 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
{ "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 }
Restore a deleted policy by ID
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.
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.
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.
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.
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) PatchPolicy(patchPolicyOptions *PatchPolicyOptions) (result *Policy, response *core.DetailedResponse, err error)
(iamPolicyManagement *IamPolicyManagementV1) PatchPolicyWithContext(ctx context.Context, patchPolicyOptions *PatchPolicyOptions) (result *Policy, response *core.DetailedResponse, err error)
ServiceCall<Policy> patchPolicy(PatchPolicyOptions patchPolicyOptions)
patchPolicy(params)
patch_policy(self,
policy_id: str,
if_match: str,
*,
state: str = None,
**kwargs
) -> DetailedResponse
Auditing
Calling this method generates the following auditing event.
iam-am.policy.update
Request
Instantiate the PatchPolicyOptions
struct and set the fields to provide parameter values for the PatchPolicy
method.
Use the PatchPolicyOptions.Builder
to create a PatchPolicyOptions
object that contains the parameter values for the patchPolicy
method.
Custom Headers
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
The policy ID.
Policy attribute to be updated.
The policy state; either 'active' or 'deleted'
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The PatchPolicy options.
The policy ID.
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.
The policy state; either 'active' or 'deleted'.
The patchPolicy options.
The policy ID.
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.
The policy state; either 'active' or 'deleted'.
parameters
The policy ID.
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.
The policy state; either 'active' or 'deleted'.
parameters
The policy ID.
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.
The policy state; either 'active' or 'deleted'.
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", }'
options := iamPolicyManagementService.NewPatchPolicyOptions( examplePolicyID, examplePolicyETag, ) options.SetState("active") policy, response, err := iamPolicyManagementService.PatchPolicy(options) if err != nil { panic(err) } b, _ := json.MarshalIndent(policy, "", " ") fmt.Println(string(b))
PatchPolicyOptions patchPolicyOptions = new PatchPolicyOptions.Builder() .policyId(examplePolicyId) .ifMatch(examplePolicyEtag) .state("active") .build(); Response<Policy> response = service.patchPolicy(patchPolicyOptions).execute(); Policy policy = response.getResult(); System.out.println(policy);
const params = { policyId: examplePolicyId, ifMatch: examplePolicyETag, state: 'active' }; iamPolicyManagementService.patchPolicy(params) .then(res => { console.log(JSON.stringify(res.result, null, 2)); }) .catch(err => { console.warn(err) });
policy = iam_policy_management_service.patch_policy( policy_id=example_policy_id, if_match=example_updated_policy_etag, state='active' ).get_result() print(json.dumps(policy, indent=2))
Response
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description
The subjects associated with a policy.
Constraints: number of items = 1
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The resources associated with a policy.
Constraints: number of items ≤ 1
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
Attributes
Subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
Roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
Attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
Tags
Resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
The name of an attribute.
The value of an attribute.
The operator of an attribute.
attributes
List of access management tags.
The name of an access management tag.
The value of an access management tag.
The operator of an access management tag.
tags
resources
The href link back to the policy.
The UTC timestamp when the policy was created.
The iam ID of the entity that created the policy.
The UTC timestamp when the policy was last modified.
The iam ID of the entity that last modified the policy.
The policy state; either 'active' or 'deleted'.
The core set of properties associated with a policy.
The policy ID.
The policy type; either 'access' or 'authorization'.
Customer-defined description.
The subjects associated with a policy.
Constraints: number of items = 1
List of subject attributes.
The name of an attribute.
The value of an attribute.
attributes
subjects
A set of role cloud resource names (CRNs) granted by the policy.
Constraints: number of items ≥ 1
The role cloud resource name granted by the policy.
The display name of the role.
The description of the role.
roles
The resources associated with a policy.
Constraints: number of items ≤ 1
List of resource attributes.
resources