Introduction

With the IBM Cloud® 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 calling 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 is 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 Cloud 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.

A role is a collection of actions that can be taken on a resource. For more information, see Roles.

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 URL

The IAM Policy Management API uses the following 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

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'

Additional headers

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

Transaction-Id

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

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

Rate limiting

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

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

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, we only support the following attributes: account_id, iam_id, access_group_id, type, and service_type. 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, we only support the following attributes: account_id, iam_id, access_group_id, type, and service_type. 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, we only support the following attributes: account_id, iam_id, access_group_id, type, and service_type. 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, we only support the following attributes: account_id, iam_id, access_group_id, type, and service_type. 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, we only support the following attributes: account_id, iam_id, access_group_id, type, and service_type. 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
ServiceCall<PolicyList> listPolicies(ListPoliciesOptions listPoliciesOptions)
listPolicies(params, [callback()])
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,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) ListPolicies(listPoliciesOptions *ListPoliciesOptions) (result *PolicyList, response *core.DetailedResponse, err error)

Request

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

Instantiate the ListPoliciesOptions struct and set the fields to provide 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 listPolicies options.

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.

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 ListPolicies options.

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

Response

Response type: PolicyList

Response type: PolicyList

Response type: PolicyList

Response type: PolicyList

A collection of 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.

Example responses
  • {
      "policies": [
        {
          "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "type": "access",
          "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"
        }
      ]
    }
  • {
      "policies": [
        {
          "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
          "type": "access",
          "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"
        }
      ]
    }
  • {
      "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
ServiceCall<Policy> createPolicy(CreatePolicyOptions createPolicyOptions)
createPolicy(params, [callback()])
create_policy(self,
        type: str,
        subjects: List['PolicySubject'],
        roles: List['PolicyRole'],
        resources: List['PolicyResource'],
        *,
        accept_language: str = None,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) CreatePolicy(createPolicyOptions *CreatePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

Request

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

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

Custom Headers

  • Translation language code

A policy to be created.

The createPolicy options.

parameters

  • 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

  • Translation language code.

parameters

  • 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

  • Translation language code.

The CreatePolicy options.

  • 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"
            }
          ]
        }
      ]
    }'

Response

Response type: Policy

Response type: Policy

Response type: Policy

Response type: Policy

The core set of properties associated with a policy.

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.

Example responses
  • {
      "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"
    }
  • {
      "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"
    }
  • {
      "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}
ServiceCall<Policy> updatePolicy(UpdatePolicyOptions updatePolicyOptions)
updatePolicy(params, [callback()])
update_policy(self,
        policy_id: str,
        if_match: str,
        type: str,
        subjects: List['PolicySubject'],
        roles: List['PolicyRole'],
        resources: List['PolicyResource'],
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) UpdatePolicy(updatePolicyOptions *UpdatePolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

Request

Use the UpdatePolicyOptions.Builder to create a UpdatePolicyOptions object that contains the parameter values for the updatePolicy method.

Instantiate the UpdatePolicyOptions struct and set the fields to provide 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 updatePolicy options.

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

  • 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

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

  • 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 UpdatePolicy options.

  • 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"
            }
          ]
        }
      ]
    }'

Response

Response type: Policy

Response type: Policy

Response type: Policy

Response type: Policy

The core set of properties associated with a policy.

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.

Example responses
  • {
      "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"
    }
  • {
      "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"
    }
  • {
      "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}
ServiceCall<Policy> getPolicy(GetPolicyOptions getPolicyOptions)
getPolicy(params, [callback()])
get_policy(self,
        policy_id: str,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) GetPolicy(getPolicyOptions *GetPolicyOptions) (result *Policy, response *core.DetailedResponse, err error)

Request

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

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

Path Parameters

  • The policy ID

The getPolicy options.

parameters

  • The policy ID.

parameters

  • The policy ID.

The GetPolicy options.

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

Response

Response type: Policy

Response type: Policy

Response type: Policy

Response type: Policy

The core set of properties associated with a policy.

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.

Example responses
  • {
      "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"
    }
  • {
      "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"
    }
  • {
      "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}
ServiceCall<Void> deletePolicy(DeletePolicyOptions deletePolicyOptions)
deletePolicy(params, [callback()])
delete_policy(self,
        policy_id: str,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) DeletePolicy(deletePolicyOptions *DeletePolicyOptions) (response *core.DetailedResponse, err error)

Request

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

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

Path Parameters

  • The policy ID

The deletePolicy options.

parameters

  • The policy ID.

parameters

  • The policy ID.

The DeletePolicy options.

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

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.

Example responses
  • {
      "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
    }

Get roles by filters

Get roles based on the filters. While managing roles, you may want to retrieve roles and filter by usages. This can be done through query parameters. Currently, we only support the following attributes: account_id, and service_name. Only roles that match the filter and that the caller has read access to are returned. If the caller does not have read access to any roles an empty array is returned.

Get roles based on the filters. While managing roles, you may want to retrieve roles and filter by usages. This can be done through query parameters. Currently, we only support the following attributes: account_id, and service_name. Only roles that match the filter and that the caller has read access to are returned. If the caller does not have read access to any roles an empty array is returned.

Get roles based on the filters. While managing roles, you may want to retrieve roles and filter by usages. This can be done through query parameters. Currently, we only support the following attributes: account_id, and service_name. Only roles that match the filter and that the caller has read access to are returned. If the caller does not have read access to any roles an empty array is returned.

Get roles based on the filters. While managing roles, you may want to retrieve roles and filter by usages. This can be done through query parameters. Currently, we only support the following attributes: account_id, and service_name. Only roles that match the filter and that the caller has read access to are returned. If the caller does not have read access to any roles an empty array is returned.

Get roles based on the filters. While managing roles, you may want to retrieve roles and filter by usages. This can be done through query parameters. Currently, we only support the following attributes: account_id, and service_name. Only roles that match the filter and that the caller has read access to are returned. If the caller does not have read access to any roles an empty array is returned.

GET /v2/roles
ServiceCall<RoleList> listRoles(ListRolesOptions listRolesOptions)
listRoles(params, [callback()])
list_roles(self,
        *,
        accept_language: str = None,
        account_id: str = None,
        service_name: str = None,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) ListRoles(listRolesOptions *ListRolesOptions) (result *RoleList, response *core.DetailedResponse, err error)

Request

Use the ListRolesOptions.Builder to create a ListRolesOptions object that contains the parameter values for the listRoles method.

Instantiate the ListRolesOptions struct and set the fields to provide parameter values for the ListRoles method.

Custom Headers

  • Translation language code

Query Parameters

  • The account GUID in which the roles belong to.

  • The name of service.

The listRoles options.

parameters

  • Translation language code.

  • The account GUID in which the roles belong to.

  • The name of service.

parameters

  • Translation language code.

  • The account GUID in which the roles belong to.

  • The name of service.

The ListRoles options.

  • curl -X GET 'https://iam.cloud.ibm.com/v2/roles' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

Response

Response type: RoleList

Response type: RoleList

Response type: RoleList

Response type: RoleList

A collection of roles returned by the 'list roles' operation.

Status Code

  • Roles retrieval successful.

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

Example responses
  • {
      "custom_roles": [
        {
          "id": "12345678abcd1a2ba1b21234567890ab",
          "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
          "name": "Example",
          "display_name": "Example Role",
          "description": "Custom role for example",
          "service_name": "SERVICE_NAME",
          "account_id": "ACCOUNT_ID",
          "actions": [
            "ACTION_ID_1",
            "ACTION_ID_2"
          ],
          "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",
          "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
        }
      ],
      "service_roles": [
        {
          "crn": "crn:v1:bluemix:public:iam::::serviceRole:Reader",
          "display_name": "Reader",
          "description": "Reader role for example",
          "actions": [
            "ACTION_ID_1",
            "ACTION_ID_2"
          ]
        }
      ],
      "system_roles": [
        {
          "crn": "crn:v1:bluemix:public:iam::::role:Viewer",
          "display_name": "Viewer",
          "description": "Viewer role for example",
          "actions": [
            "ACTION_ID_1",
            "ACTION_ID_2"
          ]
        }
      ]
    }
  • {
      "custom_roles": [
        {
          "id": "12345678abcd1a2ba1b21234567890ab",
          "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
          "name": "Example",
          "display_name": "Example Role",
          "description": "Custom role for example",
          "service_name": "SERVICE_NAME",
          "account_id": "ACCOUNT_ID",
          "actions": [
            "ACTION_ID_1",
            "ACTION_ID_2"
          ],
          "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",
          "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
        }
      ],
      "service_roles": [
        {
          "crn": "crn:v1:bluemix:public:iam::::serviceRole:Reader",
          "display_name": "Reader",
          "description": "Reader role for example",
          "actions": [
            "ACTION_ID_1",
            "ACTION_ID_2"
          ]
        }
      ],
      "system_roles": [
        {
          "crn": "crn:v1:bluemix:public:iam::::role:Viewer",
          "display_name": "Viewer",
          "description": "Viewer role for example",
          "actions": [
            "ACTION_ID_1",
            "ACTION_ID_2"
          ]
        }
      ]
    }
  • {
      "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 role

Creates a custom role for a specific service within the account. An account owner or a user assigned the Administrator role on the Role management service can create a custom role. Any number of actions for a single service can be mapped to the new role, but there must be at least one service-defined action to successfully create the new role.

Creates a custom role for a specific service within the account. An account owner or a user assigned the Administrator role on the Role management service can create a custom role. Any number of actions for a single service can be mapped to the new role, but there must be at least one service-defined action to successfully create the new role.

Creates a custom role for a specific service within the account. An account owner or a user assigned the Administrator role on the Role management service can create a custom role. Any number of actions for a single service can be mapped to the new role, but there must be at least one service-defined action to successfully create the new role.

Creates a custom role for a specific service within the account. An account owner or a user assigned the Administrator role on the Role management service can create a custom role. Any number of actions for a single service can be mapped to the new role, but there must be at least one service-defined action to successfully create the new role.

Creates a custom role for a specific service within the account. An account owner or a user assigned the Administrator role on the Role management service can create a custom role. Any number of actions for a single service can be mapped to the new role, but there must be at least one service-defined action to successfully create the new role.

POST /v2/roles
ServiceCall<CustomRole> createRole(CreateRoleOptions createRoleOptions)
createRole(params, [callback()])
create_role(self,
        display_name: str,
        actions: List[str],
        name: str,
        account_id: str,
        service_name: str,
        *,
        description: str = None,
        accept_language: str = None,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) CreateRole(createRoleOptions *CreateRoleOptions) (result *CustomRole, response *core.DetailedResponse, err error)

Request

Use the CreateRoleOptions.Builder to create a CreateRoleOptions object that contains the parameter values for the createRole method.

Instantiate the CreateRoleOptions struct and set the fields to provide parameter values for the CreateRole method.

Custom Headers

  • Translation language code

A role to be created.

The createRole options.

parameters

  • The display name of the role that is shown in the console.

    Constraints: 1 ≤ length ≤ 50

  • The actions of the role.

    Constraints: number of items ≥ 1, length ≥ 1

  • The name of the role that is used in the CRN. Can only be alphanumeric and has to be capitalized.

    Constraints: 1 ≤ length ≤ 30, Value must match regular expression /^[A-Z]{1}[A-Za-z0-9]{0,29}$/

  • The account GUID.

  • The service name.

  • The description of the role.

    Constraints: 1 ≤ length ≤ 250

  • Translation language code.

parameters

  • The display name of the role that is shown in the console.

    Constraints: 1 ≤ length ≤ 50

  • The actions of the role.

    Constraints: number of items ≥ 1, length ≥ 1

  • The name of the role that is used in the CRN. Can only be alphanumeric and has to be capitalized.

    Constraints: 1 ≤ length ≤ 30, Value must match regular expression /^[A-Z]{1}[A-Za-z0-9]{0,29}$/

  • The account GUID.

  • The service name.

  • The description of the role.

    Constraints: 1 ≤ length ≤ 250

  • Translation language code.

The CreateRole options.

  • curl -X POST 'https://iam.cloud.ibm.com/v2/roles' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "account_id": "ACCOUNT_ID",
      "service_name": "SERVICE_NAME",
      "actions":["ACTION_ID_1", "ACTION_ID_2"]
    }'

Response

Response type: CustomRole

Response type: CustomRole

Response type: CustomRole

Response type: CustomRole

An additional set of properties associated with a role.

Status Code

  • Role creation successful.

  • Role input is invalid.

  • The token you provided is not valid.

  • You don't have access to create the role. You must be assigned the Administrator role on the Role management service.

  • The requested resource(s) cannot be formatted using the requested media type(s).

  • A role already exists with the same name or actions in the account. You can update that role or delete it and create a new one.

  • Request body sent was formatted using an unsupported media type.

  • Exceeded maximum roles quota.

  • Too many requests have been made within a given time window.

Example responses
  • {
      "id": "12345678abcd1a2ba1b21234567890ab",
      "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "service_name": "SERVICE_NAME",
      "account_id": "ACCOUNT_ID",
      "actions": [
        "ACTION_ID_1",
        "ACTION_ID_2"
      ],
      "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",
      "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
    }
  • {
      "id": "12345678abcd1a2ba1b21234567890ab",
      "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "service_name": "SERVICE_NAME",
      "account_id": "ACCOUNT_ID",
      "actions": [
        "ACTION_ID_1",
        "ACTION_ID_2"
      ],
      "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",
      "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "invalid_body",
          "message": "The role name conflicts with an existing system-defined role name. Choose a different name."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "invalid_body",
          "message": "The role name conflicts with an existing system-defined role name. Choose a different name."
        }
      ],
      "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 role. You must be assigned the Administrator role on the Role management service."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "insufficent_permissions",
          "message": "You are not allowed to create the requested role. You must be assigned the Administrator role on the Role management service."
        }
      ],
      "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": "role_conflict_error",
          "message": "This role name is already in use. Update the existing one or change the role name to be unique.",
          "details": {
            "conflicts_with": {
              "etag": "1-847833cec3bf3f3c3231d8f9492febac",
              "role": "ROLE"
            }
          },
          "status_code": 409
        }
      ]
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_conflict_error",
          "message": "This role name is already in use. Update the existing one or change the role name to be unique.",
          "details": {
            "conflicts_with": {
              "etag": "1-847833cec3bf3f3c3231d8f9492febac",
              "role": "ROLE"
            }
          },
          "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 roles quota (<limit>) for account <account_id>."
        }
      ],
      "status_code": 422
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "request_not_processed",
          "message": "Exceeded maximum roles 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 role

Update a custom role. A role administrator might want to update an existing role by updating the display name, description, or the actions that are mapped to the role. The name, account_id, and service_name can't be changed.

Update a custom role. A role administrator might want to update an existing role by updating the display name, description, or the actions that are mapped to the role. The name, account_id, and service_name can't be changed.

Update a custom role. A role administrator might want to update an existing role by updating the display name, description, or the actions that are mapped to the role. The name, account_id, and service_name can't be changed.

Update a custom role. A role administrator might want to update an existing role by updating the display name, description, or the actions that are mapped to the role. The name, account_id, and service_name can't be changed.

Update a custom role. A role administrator might want to update an existing role by updating the display name, description, or the actions that are mapped to the role. The name, account_id, and service_name can't be changed.

PUT /v2/roles/{role_id}
ServiceCall<CustomRole> updateRole(UpdateRoleOptions updateRoleOptions)
updateRole(params, [callback()])
update_role(self,
        role_id: str,
        if_match: str,
        *,
        display_name: str = None,
        description: str = None,
        actions: List[str] = None,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) UpdateRole(updateRoleOptions *UpdateRoleOptions) (result *CustomRole, response *core.DetailedResponse, err error)

Request

Use the UpdateRoleOptions.Builder to create a UpdateRoleOptions object that contains the parameter values for the updateRole method.

Instantiate the UpdateRoleOptions struct and set the fields to provide parameter values for the UpdateRole method.

Custom Headers

  • The revision number for updating a role and must match the ETag value of the existing role. The Etag can be retrieved using the GET /v2/roles/{role_id} API and looking at the ETag response header.

Path Parameters

  • The role ID

Updated role content to be saved.

The updateRole options.

parameters

  • The role ID.

  • The revision number for updating a role and must match the ETag value of the existing role. The Etag can be retrieved using the GET /v2/roles/{role_id} API and looking at the ETag response header.

  • The display name of the role that is shown in the console.

    Constraints: 1 ≤ length ≤ 50

  • The description of the role.

    Constraints: 1 ≤ length ≤ 250

  • The actions of the role.

    Constraints: number of items ≥ 1, length ≥ 1

parameters

  • The role ID.

  • The revision number for updating a role and must match the ETag value of the existing role. The Etag can be retrieved using the GET /v2/roles/{role_id} API and looking at the ETag response header.

  • The display name of the role that is shown in the console.

    Constraints: 1 ≤ length ≤ 50

  • The description of the role.

    Constraints: 1 ≤ length ≤ 250

  • The actions of the role.

    Constraints: number of items ≥ 1, length ≥ 1

The UpdateRole options.

  • curl -X PUT 'https://iam.cloud.ibm.com/v2/roles' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -H 'If-Match: $ETAG' -d '{
      "display_name": "Example Role",
      "description": "Custom role for example",
      "actions":["ACTION_ID_1", "ACTION_ID_2"]
    }'

Response

Response type: CustomRole

Response type: CustomRole

Response type: CustomRole

Response type: CustomRole

An additional set of properties associated with a role.

Status Code

  • Role update successful.

  • Role input is invalid.

  • The token you provided is not valid.

  • You do not have access to update the role.

  • Role was not found.

  • The requested resource(s) cannot be formatted using the requested media type(s).

  • A role already exists with the same actions and account_id. You can update that role 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.

Example responses
  • {
      "id": "12345678abcd1a2ba1b21234567890ab",
      "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "service_name": "SERVICE_NAME",
      "account_id": "ACCOUNT_ID",
      "actions": [
        "ACTION_ID_1",
        "ACTION_ID_2"
      ],
      "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",
      "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
    }
  • {
      "id": "12345678abcd1a2ba1b21234567890ab",
      "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "service_name": "SERVICE_NAME",
      "account_id": "ACCOUNT_ID",
      "actions": [
        "ACTION_ID_1",
        "ACTION_ID_2"
      ],
      "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",
      "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "invalid_body",
          "message": "In order to update an existing role, a rev value must be provided."
        }
      ],
      "status_code": 400
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "invalid_body",
          "message": "In order to update an existing role, a rev value must be provided."
        }
      ],
      "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 role."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "insufficent_permissions",
          "message": "You are not allowed to update the requested role."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_not_found",
          "message": "Role with Id ROLE_ID not found."
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_not_found",
          "message": "Role with Id ROLE_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": "role_conflict_error",
          "message": "The role wasn't updated.",
          "details": {
            "conflicts_with": {
              "etag": "1-847833cec3bf3f3c3231d8f9492febac",
              "role": "ROLE"
            }
          },
          "status_code": 409
        }
      ]
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_conflict_error",
          "message": "The role wasn't updated.",
          "details": {
            "conflicts_with": {
              "etag": "1-847833cec3bf3f3c3231d8f9492febac",
              "role": "ROLE"
            }
          },
          "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 role by ID

Retrieve a role by providing a role ID.

Retrieve a role by providing a role ID.

Retrieve a role by providing a role ID.

Retrieve a role by providing a role ID.

Retrieve a role by providing a role ID.

GET /v2/roles/{role_id}
ServiceCall<CustomRole> getRole(GetRoleOptions getRoleOptions)
getRole(params, [callback()])
get_role(self,
        role_id: str,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) GetRole(getRoleOptions *GetRoleOptions) (result *CustomRole, response *core.DetailedResponse, err error)

Request

Use the GetRoleOptions.Builder to create a GetRoleOptions object that contains the parameter values for the getRole method.

Instantiate the GetRoleOptions struct and set the fields to provide parameter values for the GetRole method.

Path Parameters

  • The role ID

The getRole options.

parameters

  • The role ID.

parameters

  • The role ID.

The GetRole options.

  • curl -X GET 'https://iam.cloud.ibm.com/v2/roles/$ROLE_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

Response

Response type: CustomRole

Response type: CustomRole

Response type: CustomRole

Response type: CustomRole

An additional set of properties associated with a role.

Status Code

  • Role retrieval successful.

  • The token you provided is not valid.

  • You do not have access to retrieve the role.

  • Role 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.

Example responses
  • {
      "id": "12345678abcd1a2ba1b21234567890ab",
      "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "service_name": "SERVICE_NAME",
      "account_id": "ACCOUNT_ID",
      "actions": [
        "ACTION_ID_1",
        "ACTION_ID_2"
      ],
      "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",
      "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
    }
  • {
      "id": "12345678abcd1a2ba1b21234567890ab",
      "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example",
      "name": "Example",
      "display_name": "Example Role",
      "description": "Custom role for example",
      "service_name": "SERVICE_NAME",
      "account_id": "ACCOUNT_ID",
      "actions": [
        "ACTION_ID_1",
        "ACTION_ID_2"
      ],
      "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",
      "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab"
    }
  • {
      "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 role."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "insufficent_permissions",
          "message": "You are not allowed to retrieve the requested role."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_not_found",
          "message": "Role with Id ROLE_ID not found."
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_not_found",
          "message": "Role with Id ROLE_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 role by ID

Delete a role by providing a role ID.

Delete a role by providing a role ID.

Delete a role by providing a role ID.

Delete a role by providing a role ID.

Delete a role by providing a role ID.

DELETE /v2/roles/{role_id}
ServiceCall<Void> deleteRole(DeleteRoleOptions deleteRoleOptions)
deleteRole(params, [callback()])
delete_role(self,
        role_id: str,
        **kwargs
    ) -> DetailedResponse
(iamPolicyManagement *IamPolicyManagementV1) DeleteRole(deleteRoleOptions *DeleteRoleOptions) (response *core.DetailedResponse, err error)

Request

Use the DeleteRoleOptions.Builder to create a DeleteRoleOptions object that contains the parameter values for the deleteRole method.

Instantiate the DeleteRoleOptions struct and set the fields to provide parameter values for the DeleteRole method.

Path Parameters

  • The role ID

The deleteRole options.

parameters

  • The role ID.

parameters

  • The role ID.

The DeleteRole options.

  • curl -X DELETE 'https://iam.cloud.ibm.com/v2/roles/$ROLE_ID' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

Response

Status Code

  • Role deletion successful.

  • The token you provided is not valid.

  • You do not have access to delete the role.

  • Role was not found.

  • Too many requests have been made within a given time window.

Example responses
  • {
      "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 role."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "insufficent_permissions",
          "message": "You are not allowed to delete the requested role."
        }
      ],
      "status_code": 403
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_not_found",
          "message": "Role with Id ROLE_ID not found."
        }
      ],
      "status_code": 404
    }
  • {
      "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
      "errors": [
        {
          "code": "role_not_found",
          "message": "Role with Id ROLE_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
    }