Introduction

With the 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. More details on IAM can be found at: IBM Cloud Identity and Access Management.

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

The subject describes who is being granted access. The subject can be an iam_id or an access group id.
The iam_id of the entity that you are giving access to. This 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. See: Setting up access groups or IAM Access Groups.

Example format for supported subject types

Type Attribute name Attribute value format example
User iam_id IBMid-123456...
Service ID iam_id iam-ServiceId-12345...
Access Group access_group_id AccessGroupId-12345...

Two types of policies are supported access policies and authorization policies. These are described in more detail here: Create a policy

A role is a collection of actions that can be taken on a resource. Role details can be found here: IBM Cloud Identity and Access Management

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 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 could not be found.
409 Conflict The entity is already in the requested state.
415 Unsupported Media Type Request body sent was formatted 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 could not 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 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 given time window. The response includes a Retry-After header to indicate the time in seconds to wait before sending the next request.

When working with the Policy Management API, it may be helpful to be aware of other IAM services. View Identity Service to learn about api key, service ID, and token creation. View 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 /v1/policies
Request

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.

Response

A list 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

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
Request

A policy to be created.

Response

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.

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

Example responses

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}
Request

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.

Response

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.

  • 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

Retrieve a policy by ID

Retrieve a policy by providing a policy ID.

GET /v1/policies/{policy_id}
Request

Path Parameters

  • The policy ID

Response

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

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}
Request

Path Parameters

  • The policy ID

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