IAM Policy Management API - IBM Cloud API Docs

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.

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

Example API request

curl -X {request_method} "https://iam.cloud.ibm.com/{method_endpoint}"

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.

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.

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.

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 /v1/policies

/v1/policies

Request

Custom Headers

Authorization
string
IAM token
Accept-Language
string
Translation language code

Query Parameters

account_id
string
The account GUID in which the policies belong to.
iam_id
string
The IAM ID used to identify the subject.
access_group_id
string
The access group id.
type
string
The type of policy (access or authorization).
service_type
string
The type of service.

```
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 Body

policy_list

Status Code

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

Example responses

Status 200

{
  "policies": [
    {
      "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
      "type": "access",
      "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"
    }
  ]
}

Status 400

{
  "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
}

Status 401

{
  "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
}

Status 406

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

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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.

POST /v1/policies

/v1/policies

Request

Custom Headers

Authorization
string
IAM token
Accept-Language
string
Translation language code

Request Body

policy_request

A policy to be created.

Example request

curl -X POST \
'https://iam.cloud.ibm.com/v1/policies' \
-H 'Authorization: Bearer $TOKEN'\
-H 'Content-Type: application/json'\
-d '{
  "type": "access",
  "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"
        }
      ]
    }
  ]
}'curl -X POST \
'https://iam.cloud.ibm.com/v1/policies' \
-H 'Authorization: Bearer $TOKEN'\
-H 'Content-Type: application/json'\
-d '{
  "type": "access",
  "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 Body

policy_response

Status Code

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

Example responses

Status 201

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "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",
  "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"
}

Status 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_body",
      "message": "The following role(s) had multiple entries: crn:v1:bluemix:public:iam::::role:Viewer"
    }
  ],
  "status_code": 400
}

Status 401

{
  "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
}

Status 403

{
  "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
}

Status 406

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

Status 409

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

Status 415

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

Status 422

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

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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.

PUT /v1/policies/{policy_id}

/v1/policies/{policy_id}

Request

Custom Headers

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

Path Parameters

policy_id
string
The policy ID

Request Body

policy_request

Updated policy content to be saved.

Example request

curl -X PUT \
'https://iam.cloud.ibm.com/v1/policies' \
-H 'Authorization: Bearer $TOKEN'\
-H 'Content-Type: application/json'\
-H 'If-Match: $ETAG'\
-d '{
  "type": "access",
  "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"
        }
      ]
    }
  ]
}'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",
  "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 Body

policy_response

Status Code

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

Example responses

Status 200

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "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",
  "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"
}

Status 400

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

Status 401

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

Status 403

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

Status 404

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

Status 406

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

Status 409

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

Status 415

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

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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.

GET /v1/policies/{policy_id}

/v1/policies/{policy_id}

Request

Path Parameters

policy_id
string
The policy ID

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

Response

Response Body

policy_response

Status Code

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

Example responses

Status 200

{
  "id": "12345678-abcd-1a2b-a1b2-1234567890ab",
  "type": "access",
  "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",
  "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"
}

Status 401

{
  "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
}

Status 403

{
  "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
}

Status 404

{
  "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
}

Status 406

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

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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 /v1/policies/{policy_id}

/v1/policies/{policy_id}

Request

Path Parameters

policy_id
string
The policy ID

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

Response

Status Code

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

Example responses

Status 400

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

Status 401

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

Status 403

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

Status 404

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

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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 /v2/roles

/v2/roles

Request

Custom Headers

Authorization
string
IAM token
Accept-Language
string
Translation language code

Query Parameters

account_id
string
The account GUID in which the roles belong to.
service_name
string
The name of service.

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

Response

Response Body

role_list

Status Code

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

Example responses

Status 200

{
  "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"
      ]
    }
  ]
}

Status 401

{
  "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
}

Status 406

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

Status 429

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

Create a role

Creates a role specified for the account and service.

POST /v2/roles

/v2/roles

Request

Custom Headers

Authorization
string
IAM token
Accept-Language
string
Translation language code

Request Body

role_post_request

A role to be created.

```
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 Body

custom_role_response

Status Code

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

Example responses

Status 201

{
  "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"
}

Status 400

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "The role name is conflicting with system define role, please choose another name."
    }
  ],
  "status_code": 400
}{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "invalid_body",
      "message": "The role name is conflicting with system define role, please choose another name."
    }
  ],
  "status_code": 400
}

Status 401

{
  "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
}

Status 403

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

Status 406

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

Status 409

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "role_conflict_error",
      "message": "This role name has already been used, please update the existing one or change the role name.",
      "details": {
        "conflicts_with": {
          "etag": "1-847833cec3bf3f3c3231d8f9492febac",
          "role": "ROLE"
        }
      },
      "status_code": 409
    }
  ]
}{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "role_conflict_error",
      "message": "This role name has already been used, please update the existing one or change the role name.",
      "details": {
        "conflicts_with": {
          "etag": "1-847833cec3bf3f3c3231d8f9492febac",
          "role": "ROLE"
        }
      },
      "status_code": 409
    }
  ]
}

Status 415

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

Status 422

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "request_not_processed",
      "message": "Exceeded maximum 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
}

Status 429

{
  "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 role specified for the account and service. A role administrator might want to update an existing role. The role name, account_id, and service_name cannot be changed.

PUT /v2/roles/{role_id}

/v2/roles/{role_id}

Request

Custom Headers

If-Match
string
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

role_id
string
The role ID

Request Body

role_put_request

Updated role content to be saved.

```
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 Body

custom_role_response

Status Code

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

Example responses

Status 200

{
  "id": "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"
}

Status 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_body",
      "message": "In order to update an existing role, a rev value must be provided."
    }
  ],
  "status_code": 400
}

Status 401

{
  "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
}

Status 403

{
  "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
}

Status 404

{
  "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
}

Status 406

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

Status 409

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "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
    }
  ]
}

Status 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": "unsupported_content_type",
      "message": "The supported media type for this API is 'application/json'."
    }
  ],
  "status_code": 415
}

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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.

GET /v2/roles/{role_id}

/v2/roles/{role_id}

Request

Path Parameters

role_id
string
The role ID

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

Response

Response Body

custom_role_response

Status Code

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

Example responses

Status 200

{
  "id": "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"
}

Status 401

{
  "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
}

Status 403

{
  "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
}

Status 404

{
  "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
}

Status 406

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

Status 429

{
  "trace": "26f0b2491ed6425c9e7b0c08a3a645f7",
  "errors": [
    {
      "code": "too_many_requests",
      "message": "Too many requests."
    }
  ],
  "status_code": 429
}{
  "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 /v2/roles/{role_id}

/v2/roles/{role_id}

Request

Path Parameters

role_id
string
The role ID

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

Response

Status Code

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

Example responses

Status 401

{
  "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
}

Status 403

{
  "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
}

Status 404

{
  "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
}

Status 429

{
  "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
}

Introduction

Endpoint URL

Error handling

Authentication

Additional headers

Transaction-Id

Rate limiting

Related APIs

Methods

Get policies by attributes

Custom Headers

Authorization

Accept-Language

Query Parameters

account_id

iam_id

access_group_id

type

service_type

Response Body

policies

Status Code

200

400

401

406

429

Create a policy

Access

Authorization

Custom Headers

Authorization

Accept-Language

Request Body

type

subjects

attributes

name

value

roles

role_id

resources

attributes

name

value

operator

Response Body

id

type

subjects

attributes

name

value

roles

role_id

display_name

description

resources

attributes

name

value

operator

href

created_at

created_by_id

last_modified_at

last_modified_by_id

Status Code

201

400

401

403

406

409

415

422

429

Update a policy

Access

Authorization