Get policies by attributes

GET /v1/policies

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID that the policies belong to.

iam_id

string

Optional IAM ID used to identify the subject.

access_group_id

string

Optional access group id.

type

string

Optional type of policy.

service_type

string

Optional type of service.

tag_name

string

Optional name of the access tag in the policy.

tag_value

string

Optional value of the access tag in the policy.

sort

string

Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field. Example '-last_modified_at'

format

string

Include additional data per policy returned

  • `include_last_permit` - returns details of when the policy last granted a permit decision and the number of times it has done so
  • `display` - returns the list of all actions included in each of the policy roles

state

string

The state of the policy.

  • `active` - returns active policies
  • `deleted` - returns non-active policies

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Policies retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

policies

array

List of policies.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Create a policy

POST /v1/policies

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

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.create

Request

Request Body

PolicyRequest

A policy to be created.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Customer-defined description

subjects

Required *

array

The subjects associated with a policy.

roles

Required *

array

A set of role Cloud Resource Names (CRNs) granted by the policy.

resources

Required *

array

The resources associated with a policy.

Response

201 - Policy creation successful.

id

string

The policy ID.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Customer-defined description

subjects

array

The subjects associated with a policy.

roles

array

A set of role Cloud Resource Names (CRNs) granted by the policy.

resources

array

The resources associated with a policy.

href

string

The href links back to the policy.

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state.

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum policies quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Update a policy

PUT /v1/policies/{policy_id}

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

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.update

Request

Request Body

PolicyRequest

Updated policy content to be saved.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Customer-defined description

subjects

Required *

array

The subjects associated with a policy.

roles

Required *

array

A set of role Cloud Resource Names (CRNs) granted by the policy.

resources

Required *

array

The resources associated with a policy.

Path Parameters

Query Parameters

Response

200 - Policy update successful.

id

string

The policy ID.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Customer-defined description

subjects

array

The subjects associated with a policy.

roles

array

A set of role Cloud Resource Names (CRNs) granted by the policy.

resources

array

The resources associated with a policy.

href

string

The href links back to the policy.

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state.

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

409 - A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Retrieve a policy by ID

GET /v1/policies/{policy_id}

Retrieve a policy by providing a policy ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.read

Request

Response

200 - Policy retrieval successful.

id

string

The policy ID.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Customer-defined description

subjects

array

The subjects associated with a policy.

roles

array

A set of role Cloud Resource Names (CRNs) granted by the policy.

resources

array

The resources associated with a policy.

href

string

The href links back to the policy.

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state.

template

TemplateMetadata

The details of the IAM template that was used to create an enterprise-managed policy in your account. When returned, this indicates that the policy is created from and managed by a template in the root enterprise account.

401 -

403 - You do not have access to retrieve the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Delete a policy by ID

DELETE /v1/policies/{policy_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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.delete

Request

Response

204 - Policy deletion successful.

400 - Policy was not valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Restore a deleted policy by ID

PATCH /v1/policies/{policy_id}

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.update

Request

Request Body

PatchPolicyRequest

Policy attribute to be updated.

state

string

The policy state.

Path Parameters

Query Parameters

Response

200 - Policy successfully restored.

id

string

The policy ID.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Customer-defined description

subjects

array

The subjects associated with a policy.

roles

array

A set of role Cloud Resource Names (CRNs) granted by the policy.

resources

array

The resources associated with a policy.

href

string

The href links back to the policy.

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state.

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

415 -

429 -

Get policies by attributes

GET /v2/policies

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID in which the policies belong to.

iam_id

string

Optional IAM ID used to identify the subject.

access_group_id

string

Optional access group id.

type

string

Optional type of policy.

service_type

string

Optional type of service.

service_name

string

Optional name of service.

service_group_id

string

Optional ID of service group.

sort

string

Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field, for example, '-last_modified_at'. Note that last permit information is only included when 'format=include_last_permit', for example, "format=include_last_permit&sort=last_permit_at" Example fields that can be sorted on: - 'type' - 'href' - 'created_at' - 'created_by_id' - 'last_modified_at' - 'last_modified_by_id' - 'state' - 'last_permit_at' - 'last_permit_frequency'

format

string

Include additional data per policy returned

  • `include_last_permit` - returns details of when the policy last granted a permit decision and the number of times it has done so
  • `display` - returns the list of all actions included in each of the policy roles and translations for all relevant fields

state

string

The state of the policy.

  • `active` - returns active policies
  • `deleted` - returns non-active policies

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Policies retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

policies

array

List of policies.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Access

To create an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.

Currently, we support two types of patterns:

  1. `time-based`: Used to specify a time-based restriction

Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ```

The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.

  1. `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.

Combine conditions to specify an attribute-based condition using AND/OR-based operators.

For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```

In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.

Authorization

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

Attribute Operators

Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.

Attribute Validations

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

Create a policy

POST /v2/policies

Creates a policy to grant access between a subject and a resource. Currently, there is one type of a v2/policy: access. A policy administrator might want to create an access policy that grants access to a user, service-id, or an access group.

Access

To create an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.

Currently, we support two types of patterns:

  1. `time-based`: Used to specify a time-based restriction

Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ```

The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.

  1. `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.

Combine conditions to specify an attribute-based condition using AND/OR-based operators.

For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```

In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.

Authorization

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

Attribute Operators

Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.

Attribute Validations

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.create

Request

Request Body

CreateUpdateV2PolicyRequest

A policy to be created.

control

Required *

Control

Specifies the type of access that is granted by the policy.

grant

Required *

object

Permission is granted by the policy.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy.

subject

V2PolicySubject

The subject attributes for whom the policy grants access.

attributes

Required *

array

List of subject attributes associated with policy.

resource

V2PolicyResource

The resource attributes to which the policy grants access.

attributes

Required *

array

List of resource attributes to which the policy grants access.

tags

array

Optional list of resource tags to which the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

V2PolicyRule

Additional access conditions associated with the policy.

Response

201 - Policy creation successful.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy.

subject

V2PolicySubject

The subject attributes for whom the policy grants access.

resource

V2PolicyResource

The resource attributes to which the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

V2PolicyRule

Additional access conditions associated with the policy.

id

string

The policy ID.

href

string

The href URL that links to the policies API by policy ID.

control

ControlResponse

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state, either 'deleted' or 'active'.

last_permit_at

string

The optional last permit time of policy, when passing query parameter format=include_last_permit.

last_permit_frequency

integer

The optional count of times that policy has provided a permit, when passing query parameter format=include_last_permit.

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum policies quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Access

To update an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.

Currently, we support two types of patterns:

  1. `time-based`: Used to specify a time-based restriction

Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ``` The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.

  1. `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.

Combine conditions to specify an attribute-based condition using AND/OR-based operators.

For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```

In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.

Authorization

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

Attribute Operators

Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.

Attribute Validations

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

Update a policy

PUT /v2/policies/{id}

Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy.

Access

To update an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.

Currently, we support two types of patterns:

  1. `time-based`: Used to specify a time-based restriction

Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ``` The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.

  1. `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.

Combine conditions to specify an attribute-based condition using AND/OR-based operators.

For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```

In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.

Authorization

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

Attribute Operators

Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.

Attribute Validations

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.update

Request

Request Body

CreateUpdateV2PolicyRequest

Updated policy content to be saved.

control

Required *

Control

Specifies the type of access that is granted by the policy.

grant

Required *

object

Permission is granted by the policy.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy.

subject

V2PolicySubject

The subject attributes for whom the policy grants access.

attributes

Required *

array

List of subject attributes associated with policy.

resource

V2PolicyResource

The resource attributes to which the policy grants access.

attributes

Required *

array

List of resource attributes to which the policy grants access.

tags

array

Optional list of resource tags to which the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

V2PolicyRule

Additional access conditions associated with the policy.

Path Parameters

Query Parameters

Response

200 - Policy update successful.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy.

subject

V2PolicySubject

The subject attributes for whom the policy grants access.

resource

V2PolicyResource

The resource attributes to which the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

V2PolicyRule

Additional access conditions associated with the policy.

id

string

The policy ID.

href

string

The href URL that links to the policies API by policy ID.

control

ControlResponse

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state, either 'deleted' or 'active'.

last_permit_at

string

The optional last permit time of policy, when passing query parameter format=include_last_permit.

last_permit_frequency

integer

The optional count of times that policy has provided a permit, when passing query parameter format=include_last_permit.

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

409 - A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Retrieve a policy by ID

GET /v2/policies/{id}

Retrieve a policy by providing a policy ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.read

Request

Path Parameters

Query Parameters

format

string

Include additional data for policy returned

  • `include_last_permit` - returns details of when the policy last granted a permit decision and the number of times it has done so
  • `display` - returns the list of all actions included in each of the policy roles and translations for all relevant fields

Response

200 - Policy retrieval successful.

type

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy.

subject

V2PolicySubject

The subject attributes for whom the policy grants access.

resource

V2PolicyResource

The resource attributes to which the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

V2PolicyRule

Additional access conditions associated with the policy.

id

string

The policy ID.

href

string

The href URL that links to the policies API by policy ID.

control

ControlResponse

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

state

string

The policy state, either 'deleted' or 'active'.

last_permit_at

string

The optional last permit time of policy, when passing query parameter format=include_last_permit.

last_permit_frequency

integer

The optional count of times that policy has provided a permit, when passing query parameter format=include_last_permit.

template

TemplateMetadata

The details of the IAM template that was used to create an enterprise-managed policy in your account. When returned, this indicates that the policy is created from and managed by a template in the root enterprise account.

401 -

403 - You do not have access to retrieve the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Delete a policy by ID

DELETE /v2/policies/{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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.delete

Request

Response

204 - Policy deletion successful.

400 - Policy was not valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Get roles by filters

GET /v2/roles

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, service_name, service_group_id, source_service_name and policy_type. Both service_name and service_group_id attributes are mutually exclusive. 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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam.policy.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.role.read

Request

Path Parameters

Query Parameters

account_id

string

Optional account GUID in which the roles belong to.

service_name

string

Optional name of IAM enabled service.

source_service_name

string

Optional name of source IAM enabled service.

policy_type

string

Optional Policy Type.

service_group_id

string

Optional id of service group.

Response

200 - Roles retrieval successful.

custom_roles

array

List of custom roles.

service_roles

array

List of service roles.

system_roles

array

List of system roles.

401 -

404 -

406 -

429 -

Create a role

POST /v2/roles

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.customRole.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.role.create

Request

Request Body

RolePostRequest

A role to be created.

display_name

Required *

string

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

description

string

The description of the role.

actions

Required *

array

The actions of the role. For more information, see IAM roles and actions.

crn

string

The role Cloud Resource Name (CRN). Example CRN: 'crn:v1:ibmcloud:public:iam-access-management::a/exampleAccountId::customRole:ExampleRoleName'

name

Required *

string

The name of the role that is used in the CRN. This must be alphanumeric and capitalized.

account_id

Required *

string

The account GUID.

service_name

Required *

string

The service name.

Response

201 - Role creation successful.

id

string

The role ID. Composed of hexadecimal characters.

display_name

string

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

description

string

The description of the role.

actions

array

The actions of the role. For more information, see IAM roles and actions.

crn

string

The role Cloud Resource Name (CRN). Example CRN: 'crn:v1:ibmcloud:public:iam-access-management::a/exampleAccountId::customRole:ExampleRoleName'

name

string

The name of the role that is used in the CRN. This must be alphanumeric and capitalized.

account_id

string

The account GUID.

service_name

string

The service name.

created_at

string

The UTC timestamp when the role was created.

created_by_id

string

The IAM ID of the entity that created the role.

last_modified_at

string

The UTC timestamp when the role was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

href

string

The href links back to the role.

400 - Role input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

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

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

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

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum roles quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Update a role

PUT /v2/roles/{role_id}

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.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.customRole.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.role.update

Request

Request Body

Role

Updated role content to be saved.

display_name

Required *

string

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

description

string

The description of the role.

actions

Required *

array

The actions of the role. For more information, see IAM roles and actions.

crn

string

The role Cloud Resource Name (CRN). Example CRN: 'crn:v1:ibmcloud:public:iam-access-management::a/exampleAccountId::customRole:ExampleRoleName'

Path Parameters

Query Parameters

Response

200 - Role update successful.

id

string

The role ID. Composed of hexadecimal characters.

display_name

string

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

description

string

The description of the role.

actions

array

The actions of the role. For more information, see IAM roles and actions.

crn

string

The role Cloud Resource Name (CRN). Example CRN: 'crn:v1:ibmcloud:public:iam-access-management::a/exampleAccountId::customRole:ExampleRoleName'

name

string

The name of the role that is used in the CRN. This must be alphanumeric and capitalized.

account_id

string

The account GUID.

service_name

string

The service name.

created_at

string

The UTC timestamp when the role was created.

created_by_id

string

The IAM ID of the entity that created the role.

last_modified_at

string

The UTC timestamp when the role was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

href

string

The href links back to the role.

400 - Role input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the role.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

409 - A role already exists with the same actions and account_id. You can update that role or delete it and create a new one.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Retrieve a role by ID

GET /v2/roles/{role_id}

Retrieve a role by providing a role ID.

Auditing

Calling this method generates the following auditing event.

  • iam-am.role.read

Request

Response

200 - Role retrieval successful.

id

string

The role ID. Composed of hexadecimal characters.

display_name

string

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

description

string

The description of the role.

actions

array

The actions of the role. For more information, see IAM roles and actions.

crn

string

The role Cloud Resource Name (CRN). Example CRN: 'crn:v1:ibmcloud:public:iam-access-management::a/exampleAccountId::customRole:ExampleRoleName'

name

string

The name of the role that is used in the CRN. This must be alphanumeric and capitalized.

account_id

string

The account GUID.

service_name

string

The service name.

created_at

string

The UTC timestamp when the role was created.

created_by_id

string

The IAM ID of the entity that created the role.

last_modified_at

string

The UTC timestamp when the role was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy.

href

string

The href links back to the role.

401 -

403 - You do not have access to retrieve the role.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Delete a role by ID

DELETE /v2/roles/{role_id}

Delete a role by providing a role ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.customRole.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.role.delete

Request

Response

204 - Role deletion successful.

401 -

403 - You do not have access to delete the role.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

List policy templates by attributes

GET /v1/policy_templates

List policy templates and filter by attributes by using query parameters. The following attributes are supported: `account_id`, `policy_service_name`, `policy_service_type`, `policy_service_group_id` and `policy_type`. `account_id` is a required query parameter. These attributes `policy_service_name`, `policy_service_type` and `policy_service_group_id` are mutually exclusive. Only policy templates 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 policy templates an empty array is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID that the policy templates belong to.

state

string

The policy template state.

name

string

The policy template name.

policy_service_type

string

Service type, Optional.

policy_service_name

string

Service name, Optional.

policy_service_group_id

string

Service group id, Optional.

policy_type

string

Policy type, Optional.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Policy Templates retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

policy_templates

array

List of policy templates.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Create a policy template

POST /v1/policy_templates

Create a policy template. Policy templates define a policy without requiring a subject, and you can use them to grant access to multiple subjects.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.create

Request

Request Body

PolicyTemplateRequest

A policy template to be created.

name

Required *

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

account_id

Required *

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template.

policy

Required *

TemplatePolicy

The core set of properties associated with the template's policy object.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy. This is shown in child accounts when an access group or trusted profile template uses the policy template to assign access.

resource

object

The resource attributes to which the policy grants access.

subject

object

The subject attributes for whom the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

object

Additional access conditions associated with the policy.

control

object

Specifies the type of access that is granted by the policy.

Response

201 - Policy Template creation successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

version

string

Template version.

committed

boolean

Committed status of the template version.

policy

TemplatePolicy

The core set of properties associated with the template's policy object.

state

string

State of policy template.

id

string

The policy template ID.

href

string

The href URL that links to the policy templates API by policy template ID.

created_at

string

The UTC timestamp when the policy template was created.

created_by_id

string

The IAM ID of the entity that created the policy template.

last_modified_at

string

The UTC timestamp when the policy template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy template.

counts

TemplateCountData

policy template count details

400 - Policy Template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A policy template already exists for the .... TBD

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum policy templates quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Retrieve latest version of a policy template

GET /v1/policy_templates/{policy_template_id}

Retrieve the latest version of a policy template by providing a policy template ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.read

Request

Path Parameters

Query Parameters

state

string

The policy template state.

Response

200 - Policy Template retrieval successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

version

string

Template version.

committed

boolean

Committed status of the template version.

policy

TemplatePolicy

The core set of properties associated with the template's policy object.

state

string

State of policy template.

id

string

The policy template ID.

href

string

The href URL that links to the policy templates API by policy template ID.

created_at

string

The UTC timestamp when the policy template was created.

created_by_id

string

The IAM ID of the entity that created the policy template.

last_modified_at

string

The UTC timestamp when the policy template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy template.

401 -

403 - You do not have access to retrieve the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Delete a policy template

DELETE /v1/policy_templates/{policy_template_id}

Delete a policy template by providing the policy template ID. This deletes all versions of this template. A policy template can't be deleted if any version of the template is assigned to one or more child accounts. You must remove the policy assignments first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.delete

Request

Response

204 - Policy Template deletion successful.

400 - Policy Template was not valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Create a new policy template version

POST /v1/policy_templates/{policy_template_id}/versions

Create a new version of a policy template. Use this if you need to make updates to a policy template that is committed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.create

Request

Request Body

PolicyTemplateVersionRequest

A policy template to be created.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

policy

Required *

TemplatePolicy

The core set of properties associated with the template's policy object.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy. This is shown in child accounts when an access group or trusted profile template uses the policy template to assign access.

resource

object

The resource attributes to which the policy grants access.

subject

object

The subject attributes for whom the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

object

Additional access conditions associated with the policy.

control

object

Specifies the type of access that is granted by the policy.

committed

boolean

Committed status of the template version.

Response

201 - Policy Template creation successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

version

string

Template version.

committed

boolean

Committed status of the template version.

policy

TemplatePolicy

The core set of properties associated with the template's policy object.

state

string

State of policy template.

id

string

The policy template ID.

href

string

The href URL that links to the policy templates API by policy template ID.

created_at

string

The UTC timestamp when the policy template was created.

created_by_id

string

The IAM ID of the entity that created the policy template.

last_modified_at

string

The UTC timestamp when the policy template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy template.

counts

TemplateCountData

policy template count details

400 - Policy Template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A policy template already exists for the .... TBD

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum policies templates quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Retrieve policy template versions

GET /v1/policy_templates/{policy_template_id}/versions

Retrieve the versions of a policy template by providing a policy template ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.read

Request

Path Parameters

Query Parameters

state

string

The policy template state.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Policy Template versions retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

versions

array

List of policy templates versions.

401 -

403 - You do not have access to retrieve the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Update a policy template version

PUT /v1/policy_templates/{policy_template_id}/versions/{version}

Update a specific version of a policy template. You can use this only if the version isn't committed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.update

Request

Request Body

PolicyTemplateVersionRequest

Updated policy template content to be saved.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

policy

Required *

TemplatePolicy

The core set of properties associated with the template's policy object.

type

Required *

string

The policy type; either 'access' or 'authorization'.

description

string

Description of the policy. This is shown in child accounts when an access group or trusted profile template uses the policy template to assign access.

resource

object

The resource attributes to which the policy grants access.

subject

object

The subject attributes for whom the policy grants access.

pattern

string

Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.

rule

object

Additional access conditions associated with the policy.

control

object

Specifies the type of access that is granted by the policy.

committed

boolean

Committed status of the template version.

Path Parameters

Query Parameters

Response

200 - Policy Template version update successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

version

string

Template version.

committed

boolean

Committed status of the template version.

policy

TemplatePolicy

The core set of properties associated with the template's policy object.

state

string

State of policy template.

id

string

The policy template ID.

href

string

The href URL that links to the policy templates API by policy template ID.

created_at

string

The UTC timestamp when the policy template was created.

created_by_id

string

The IAM ID of the entity that created the policy template.

last_modified_at

string

The UTC timestamp when the policy template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy template.

400 - Policy template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

409 - A policy template already exists ... TBD

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Delete a policy template version

DELETE /v1/policy_templates/{policy_template_id}/versions/{version}

Delete a specific version of a policy template by providing a policy template ID and version number. You can't delete a policy template version that is assigned to one or more child accounts. You must remove the policy assignments first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.delete

Request

Response

204 - Policy Template deletion successful.

400 - Policy Template was not valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Retrieve a policy template version

GET /v1/policy_templates/{policy_template_id}/versions/{version}

Retrieve a policy template by providing a policy template ID and version number.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.read

Request

Response

200 - Policy Template retrieval successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the policy template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the policy for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

version

string

Template version.

committed

boolean

Committed status of the template version.

policy

TemplatePolicy

The core set of properties associated with the template's policy object.

state

string

State of policy template.

id

string

The policy template ID.

href

string

The href URL that links to the policy templates API by policy template ID.

created_at

string

The UTC timestamp when the policy template was created.

created_by_id

string

The IAM ID of the entity that created the policy template.

last_modified_at

string

The UTC timestamp when the policy template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy template.

401 -

403 - You do not have access to retrieve the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Commit a policy template version

POST /v1/policy_templates/{policy_template_id}/versions/{version}/commit

Commit a policy template version. You can make no further changes to the policy template once it's committed. If you need to make updates after committing a version, create a new version.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-template.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyTemplate.update

Request

Response

204 - Policy Template version update successful.

400 - Policy template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the policy template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

415 -

429 -

Get policy template assignments

GET /v1/policy_assignments

Get policy template assignments by attributes. The following attributes are supported: `account_id`, `template_id`, `template_version`, `sort`. `account_id` is a required query parameter. Only policy template assignments 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 policy template assignments an empty array is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-assignment.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyAssignment.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID in which the policies belong to.

template_id

string

Optional template id.

template_version

string

Optional policy template version.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Policy template assignments retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

assignments

array

List of policy assignments.

400 - The request that you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Create a policy authorization template assignment

POST /v1/policy_assignments

Assign a policy template to child accounts and account groups. This creates the policy in the accounts and account groups that you specify.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-assignment.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyAssignment.create

Request

Request Body

PolicyAssignmentV1Request

A policy assignment to be created.

target

Required *

AssignmentTargetDetails

assignment target account and type

type

Required *

string

Assignment target type

id

Required *

string

ID of the target account

templates

Required *

array

List of template details for policy assignment

Response

201 - Policy assignment creation successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

assignments

array

Response of policy assignments.

400 - Policy assignment input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the policy.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A policy assignment exists for the given template ID, version, and target account.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Retrieve a policy assignment

GET /v1/policy_assignments/{assignment_id}

Retrieve a policy template assignment by providing a policy assignment ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-assignment.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyAssignment.read

Request

Path Parameters

Query Parameters

version

Required *

string

specify version of response body format

Response

200 - Policy assignment retrieval successful.

401 -

403 - You do not have access to retrieve the policy assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Update a policy authorization type assignment

PATCH /v1/policy_assignments/{assignment_id}

Update a policy assignment by providing a policy assignment ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-assignment.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyAssignment.update

Request

Request Body

UpdatePolicyAssignmentRequest

A policy assignment to be created.

template_version

Required *

string

The policy template version to update to.

Path Parameters

Query Parameters

version

Required *

string

specify version of response body format

Response

200 - Policy assignment updates successful.

target

AssignmentTargetDetails

assignment target account and type

id

string

Policy assignment ID.

account_id

string

The account GUID that the policies assignments belong to.

href

string

The href URL that links to the policies assignments API by policy assignment ID.

created_at

string

The UTC timestamp when the policy assignment was created.

created_by_id

string

The IAM ID of the entity that created the policy assignment.

last_modified_at

string

The UTC timestamp when the policy assignment was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the policy assignment.

resources

array

Object for each account assigned.

subject

PolicyAssignmentV1Subject

Subject details of access type assignment.

template

AssignmentTemplateDetails

policy template details

status

string

The policy assignment status.

401 -

403 - You do not have access to retrieve the policy assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Remove a policy assignment

DELETE /v1/policy_assignments/{assignment_id}

Remove a policy template assignment by providing a policy assignment ID. You can't delete a policy assignment if the status is "in_progress".

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.policy-assignment.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.policyAssignment.delete

Request

Response

204 - Policy assignment deletion successful.

400 - Policy assignment was not in valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to remove the policy assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Retrieve Access Management account settings by account ID

GET /v1/accounts/{account_id}/settings/access_management

Retrieve Access Management settings for an account by providing the account ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.settings.read

Request

Response

200 - Access Management account settings retrieval successful.

external_account_identity_interaction

ExternalAccountIdentityInteraction

How external accounts can interact in relation to the requested account.

401 -

403 - You do not have access to retrieve the account settings.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

External Account Identity Interaction

Update the way identities within an external account are allowed to interact with the requested account by providing:

  • the `account_id` as a parameter
  • one or more external account ID(s) and state for the specific identity in the request body

External account identity interaction includes the following `identity_types`: `user` (user identities that are defined as IBMid's), `service_id` (defined as IAM ServiceIds), `service` (defined by a service’s CRN). To update an Identity’s setting, the `state` and `external_allowed_accounts` fields are required.

Different identity states are:

  • "enabled": An identity type is allowed to access resources in the account provided it has access policies on those resources.
  • "limited": An identity type is allowed to access resources in the account provided it has access policies on those resources AND it is associated with either the account the resources are in or one of the allowed accounts. This setting uses the "external_allowed_accounts" list.
  • "monitor": It has no direct impact on an Identity’s access. Instead, it creates AT events for access decisions as if the account were in a limited “state”.

Note: The state "enabled" is a special case. In this case, access is given to all accounts and there is no need to specify a particular list. Therefore, when updating "state" to "enabled" for an identity type "external_allowed_accounts" should be left empty. ">

Update Access Management account settings by account ID

PATCH /v1/accounts/{account_id}/settings/access_management

Update access management settings for an account.

External Account Identity Interaction

Update the way identities within an external account are allowed to interact with the requested account by providing:

  • the `account_id` as a parameter
  • one or more external account ID(s) and state for the specific identity in the request body

External account identity interaction includes the following `identity_types`: `user` (user identities that are defined as IBMid's), `service_id` (defined as IAM ServiceIds), `service` (defined by a service’s CRN). To update an Identity’s setting, the `state` and `external_allowed_accounts` fields are required.

Different identity states are:

  • "enabled": An identity type is allowed to access resources in the account provided it has access policies on those resources.
  • "limited": An identity type is allowed to access resources in the account provided it has access policies on those resources AND it is associated with either the account the resources are in or one of the allowed accounts. This setting uses the "external_allowed_accounts" list.
  • "monitor": It has no direct impact on an Identity’s access. Instead, it creates AT events for access decisions as if the account were in a limited “state”.

Note: The state "enabled" is a special case. In this case, access is given to all accounts and there is no need to specify a particular list. Therefore, when updating "state" to "enabled" for an identity type "external_allowed_accounts" should be left empty.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.settings.update

Request

Request Body

AccountSettingsAccessManagementPatch

Access Management Account Settings attribute to be updated.

external_account_identity_interaction

ExternalAccountIdentityInteractionPatch

Update to how external accounts can interact in relation to the requested account.

identity_types

object

The settings to apply for each identity type for a request.

Path Parameters

Query Parameters

Response

200 - Access Management account settings update successful.

external_account_identity_interaction

ExternalAccountIdentityInteraction

How external accounts can interact in relation to the requested account.

400 - Access Management Account settings input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to retrieve the account settings.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

List action control templates by attributes

GET /v1/action_control_templates

List action control templates and filter by attributes by using query parameters. The following attributes are supported: `account_id` `account_id` is a required query parameter. Only action control templates 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 action control templates an empty array is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID that the action control templates belong to.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Action Control Templates retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

action_control_templates

array

List of action control templates.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Create an action control template

POST /v1/action_control_templates

Create an action control template. Action control templates define a service action control.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.create

Request

Request Body

ActionControlTemplatePrototype

An action control template to be created.

name

Required *

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

account_id

Required *

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

service_name

Required *

string

The service name that the action control refers.

description

string

Description of the action control.

actions

Required *

array

List of actions to control access.

Response

201 - Action control template creation is successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

id

string

The action control template ID.

href

string

The href URL that links to the action control templates API by action control template ID.

created_at

string

The UTC timestamp when the action control template was created.

created_by_id

string

The IAM ID of the entity that created the action control template.

last_modified_at

string

The UTC timestamp when the action control template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of action control template.

400 - Action Control template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - An action control template already exists.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum action control templates quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Retrieve the latest version of an action control template

GET /v1/action_control_templates/{action_control_template_id}

Retrieve the latest version of an action control template by providing an action control template ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.read

Request

Path Parameters

Query Parameters

state

string

The action control template state.

Response

200 - Action control Template retrieval is successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

id

string

The action control template ID.

href

string

The href URL that links to the action control templates API by action control template ID.

created_at

string

The UTC timestamp when the action control template was created.

created_by_id

string

The IAM ID of the entity that created the action control template.

last_modified_at

string

The UTC timestamp when the action control template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of action control template.

401 -

403 - You do not have access to retrieve the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Delete an action control template

DELETE /v1/action_control_templates/{action_control_template_id}

Delete an action control template by providing the action control template ID. This deletes all versions of this template. An action control template can't be deleted if any version of the template is assigned to one or more child accounts. You must remove the action control assignments first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.delete

Request

Response

204 - Action control template deletion is successful.

400 - The action control template was not valid for deletion.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Create a new action control template version

POST /v1/action_control_templates/{action_control_template_id}/versions

Create a new version of an action control template. Use this if you need to make updates to an action control template that is committed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.create

Request

Request Body

ActionControlTemplateVersionPrototype

An action control template to be created.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it will change the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

service_name

Required *

string

The service name that the action control refers.

description

string

Description of the action control.

actions

Required *

array

List of actions to control access.

committed

boolean

Committed status of the template version. If committed is set to true, then the template version can no longer be updated.

Response

201 - Action control template creation successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

id

string

The action control template ID.

href

string

The href URL that links to the action control templates API by action control template ID.

created_at

string

The UTC timestamp when the action control template was created.

created_by_id

string

The IAM ID of the entity that created the action control template.

last_modified_at

string

The UTC timestamp when the action control template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of action control template.

400 - Action Control template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - An identical action control template already exists.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum action control templates quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Retrieve action control template versions

GET /v1/action_control_templates/{action_control_template_id}/versions

Retrieve the versions of an action control template by providing an action control template ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.read

Request

Path Parameters

Query Parameters

state

string

Action control template state.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Action control template versions retrieval is successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

versions

array

List of action control templates versions.

401 -

403 - You do not have access to retrieve the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Update an action control template version

PUT /v1/action_control_templates/{action_control_template_id}/versions/{version}

Update a specific version of an action control template. You can use this only if the version isn't committed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.update

Request

Request Body

ActionControlTemplateVersionPrototype

Updated action control template content to be saved.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it will change the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

service_name

Required *

string

The service name that the action control refers.

description

string

Description of the action control.

actions

Required *

array

List of actions to control access.

committed

boolean

Committed status of the template version. If committed is set to true, then the template version can no longer be updated.

Path Parameters

Query Parameters

Response

200 - Action control template version updates successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

id

string

The action control template ID.

href

string

The href URL that links to the action control templates API by action control template ID.

created_at

string

The UTC timestamp when the action control template was created.

created_by_id

string

The IAM ID of the entity that created the action control template.

last_modified_at

string

The UTC timestamp when the action control template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of action control template.

400 - Action control template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

409 - An identical action control template exists.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Delete an action control template version

DELETE /v1/action_control_templates/{action_control_template_id}/versions/{version}

Delete a specific version of an action control template by providing an action control template ID and version number. You can't delete an action control template version that is assigned to one or more child accounts. You must remove the action control assignments first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.delete

Request

Response

204 - Action control template deletion is successful.

400 - Action control template was not valid for deletion.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Retrieve an action control template version

GET /v1/action_control_templates/{action_control_template_id}/versions/{version}

Retrieve an action control template by providing an action control template ID and version number.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.read

Request

Response

200 - Action control template retrieval is successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

action_control

TemplateActionControl

The action control properties that are created in an action resource when the template is assigned.

id

string

The action control template ID.

href

string

The href URL that links to the action control templates API by action control template ID.

created_at

string

The UTC timestamp when the action control template was created.

created_by_id

string

The IAM ID of the entity that created the action control template.

last_modified_at

string

The UTC timestamp when the action control template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of action control template.

401 -

403 - You do not have access to retrieve the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Commit an action control template version

POST /v1/action_control_templates/{action_control_template_id}/versions/{version}/commit

Commit an action control template version. You cannot make any further changes to the action control template once it's committed. If you have to make updates after committing a version, create a new version.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.update

Request

Response

204 - Action control template version updates successful.

400 - Action control template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the action control template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

415 -

429 -

Get action control template assignments

GET /v1/action_control_assignments

Get action control template assignments by attributes. The following attributes are supported: `account_id`, `template_id`, `template_version`, `sort`. `account_id` is a required query parameter. Only action control template assignments with the specified attributes and accessible by the caller are returned. If the caller does not have read access to any action control template assignments, an empty array is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-assignment.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlAssignment.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID in which the action control assignment belongs to.

template_id

string

Optional template ID.

template_version

string

Optional action control template version.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Action control template assignments retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

assignments

array

List of action control assignments.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Create an action control template assignment

POST /v1/action_control_assignments

Assign an action control template to child accounts and account groups. This creates the action control in the accounts and account groups that you specify.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-assignment.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlAssignment.create

Request

Request Body

ActionControlAssignmentPrototype

An action control assignment to be created.

target

Required *

AssignmentTargetDetails

assignment target account and type

type

Required *

string

Assignment target type

id

Required *

string

ID of the target account

templates

Required *

array

List of action control template details for action control assignment.

Response

201 - Action control assignment creation is successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

assignments

array

List of action control assignments.

400 - Action control assignment input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the action control assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - An action control assignment exists for the given template ID, version, and target account.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Retrieve an action control assignment

GET /v1/action_control_assignments/{assignment_id}

Retrieve an action control template assignment by providing an action control assignment ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-assignment.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlAssignment.read

Request

Response

200 - Action control assignment retrieval is successful.

id

string

Action control assignment ID.

account_id

string

The account GUID that the action control assignments belong to.

href

string

The href URL that links to the action control assignments API by action control assignment ID.

created_at

string

The UTC timestamp when the action control assignment was created.

created_by_id

string

The IAM ID of the entity that created the action control assignment.

last_modified_at

string

The UTC timestamp when the action control assignment was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control assignment.

operation

string

The current operation of the action control assignment

resources

array

Resources created when action control template is assigned.

template

ActionControlAssignmentTemplate

The action control template id and version that will be assigned.

target

AssignmentTargetDetails

assignment target account and type

status

string

The action control assignment status.

401 -

403 - You do not have access to retrieve the action control assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Update an action control assignment

PATCH /v1/action_control_assignments/{assignment_id}

Update an action control assignment by providing an action control assignment ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-assignment.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlAssignment.update

Request

Request Body

ActionControlAssignmentPatchTemplate

An action control assignment to be created.

template_version

Required *

string

The version number of the template used to identify different versions of same template.

Path Parameters

Query Parameters

Response

200 - Action Control assignment updates successful.

id

string

Action control assignment ID.

account_id

string

The account GUID that the action control assignments belong to.

href

string

The href URL that links to the action control assignments API by action control assignment ID.

created_at

string

The UTC timestamp when the action control assignment was created.

created_by_id

string

The IAM ID of the entity that created the action control assignment.

last_modified_at

string

The UTC timestamp when the action control assignment was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the action control assignment.

operation

string

The current operation of the action control assignment

resources

array

Resources created when action control template is assigned.

template

ActionControlAssignmentTemplate

The action control template id and version that will be assigned.

target

AssignmentTargetDetails

assignment target account and type

status

string

The action control assignment status.

401 -

403 - You do not have access to retrieve the action control assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Remove an action control assignment

DELETE /v1/action_control_assignments/{assignment_id}

Remove an action control template assignment by providing an action control assignment ID. You can't delete an action control assignment if the status is "in_progress".

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-assignment.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlAssignment.delete

Request

Response

204 - Action control assignment deletion successful.

400 - Action control assignment was not in valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to remove the action control assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

List role templates by attributes

GET /v1/role_templates

List role templates and filter by attributes by using query parameters. The following attributes are supported: `account_id`, `name`, `role_name`, `role_service_name`, `state`, `limit`, `start`. `account_id` is a required query parameter. Only role templates 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 role templates an empty array is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID that the role templates belong to.

name

string

The role template name.

role_name

string

The template role name.

role_service_name

string

The template role service name.

state

string

The role template state.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Role Templates retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

role_templates

array

List of role templates.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Create role template

POST /v1/role_templates

Create a role template. Role templates define roles from an existing system or service defined role.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.create

Request

Request Body

RoleTemplatePrototype

A role template to be created.

name

Required *

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

account_id

Required *

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

role

object

The role properties that are created in an action resource when the template is assigned.

name

Required *

string

The name of the role that is used in the CRN. This must be alphanumeric and capitalized.

display_name

Required *

string

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

service_name

string

The service name that the role refers.

description

string

Description of the role.

actions

Required *

array

The actions of the role.

Response

201 - Role template creation is successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

role

object

The role properties that are created in an action resource when the template is assigned.

id

string

The role template ID.

href

string

The href URL that links to the role templates API by role template ID.

created_at

string

The UTC timestamp when the role template was created.

created_by_id

string

The IAM ID of the entity that created the role template.

last_modified_at

string

The UTC timestamp when the role template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of role template.

400 - Role template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A role template already exists.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum role templates quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Retrieve the latest version of a role template

GET /v1/role_templates/{role_template_id}

Retrieve the latest version of a role template by providing a role template ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.read

Request

Path Parameters

Query Parameters

state

string

The role template state.

Response

200 - Role Template retrieval is successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

role

object

The role properties that are created in an action resource when the template is assigned.

id

string

The role template ID.

href

string

The href URL that links to the role templates API by role template ID.

created_at

string

The UTC timestamp when the role template was created.

created_by_id

string

The IAM ID of the entity that created the role template.

last_modified_at

string

The UTC timestamp when the role template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of role template.

401 -

403 - You do not have access to retrieve the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Delete a Role template

DELETE /v1/role_templates/{role_template_id}

Delete a role template by providing the role template ID. This deletes all versions of this template. A role template can't be deleted if any version of the template is assigned to one or more child accounts. You must remove the role assignments first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.delete

Request

Response

204 - Role template deletion is successful.

400 - The role template was not valid for deletion.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Create a new role template version

POST /v1/role_templates/{role_template_id}/versions

Create a new version of a role template. Use this if you need to make updates to a role template that is committed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.create

Request

Request Body

RoleTemplateVersionPrototype

A role template to be created.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it will change the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

role

TemplateRole

The role properties that are created in an action resource when the template is assigned.

display_name

Required *

string

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

service_name

string

The service name that the role refers.

description

string

Description of the role.

actions

Required *

array

The actions of the role.

committed

boolean

Committed status of the template version. If committed is set to true, then the template version can no longer be updated.

Response

201 - Role template creation successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

role

object

The role properties that are created in an action resource when the template is assigned.

id

string

The role template ID.

href

string

The href URL that links to the role templates API by role template ID.

created_at

string

The UTC timestamp when the role template was created.

created_by_id

string

The IAM ID of the entity that created the role template.

last_modified_at

string

The UTC timestamp when the role template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of role template.

400 - Role template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - An identical role template already exists.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum role templates quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Retrieve role template versions

GET /v1/role_templates/{role_template_id}/versions

Retrieve the versions of a role template by providing a role template ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.read

Request

Path Parameters

Query Parameters

state

string

Role template state.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - Role template versions retrieval is successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

versions

array

List of role templates versions.

401 -

403 - You do not have access to retrieve the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Update a role template version

PUT /v1/role_templates/{role_template_id}/versions/{version}

Update a specific version of a role template. You can use this only if the version isn't committed.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.update

Request

Request Body

RoleTemplateVersionPrototype

Updated role template content to be saved.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it will change the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

role

TemplateRole

The role properties that are created in an action resource when the template is assigned.

display_name

Required *

string

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

service_name

string

The service name that the role refers.

description

string

Description of the role.

actions

Required *

array

The actions of the role.

committed

boolean

Committed status of the template version. If committed is set to true, then the template version can no longer be updated.

Path Parameters

Query Parameters

Response

200 - Role template version updates successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

role

object

The role properties that are created in an action resource when the template is assigned.

id

string

The role template ID.

href

string

The href URL that links to the role templates API by role template ID.

created_at

string

The UTC timestamp when the role template was created.

created_by_id

string

The IAM ID of the entity that created the role template.

last_modified_at

string

The UTC timestamp when the role template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of role template.

400 - Role template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

409 - An identical role template exists.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Delete a role template version

DELETE /v1/role_templates/{role_template_id}/versions/{version}

Delete a specific version of a role template by providing a role template ID and version number. You can't delete a role template version that is assigned to one or more child accounts. You must remove the role assignments first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.delete

Request

Response

204 - Role template deletion is successful.

400 - Role template was not valid for deletion.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to delete the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -

Retrieve a role template version

GET /v1/role_templates/{role_template_id}/versions/{version}

Retrieve a role template by providing a role template ID and version number.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.action-control-template.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.actionControlTemplate.read

Request

Response

200 - Role template retrieval is successful.

name

string

Required field when creating a new template. Otherwise, this field is optional. If the field is included, it changes the name value for all existing versions of the template.

description

string

Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.

account_id

string

Enterprise account ID where this template is created.

committed

boolean

Committed status of the template. If committed is set to true, then the template version can no longer be updated.

role

object

The role properties that are created in an action resource when the template is assigned.

id

string

The role template ID.

href

string

The href URL that links to the role templates API by role template ID.

created_at

string

The UTC timestamp when the role template was created.

created_by_id

string

The IAM ID of the entity that created the role template.

last_modified_at

string

The UTC timestamp when the role template was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role template.

version

string

The version number of the template used to identify different versions of same template.

state

string

State of role template.

401 -

403 - You do not have access to retrieve the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Commit a role template version

POST /v1/role_templates/{role_template_id}/versions/{version}/commit

Commit a role template version. You cannot make any further changes to the role template once it's committed. If you have to make updates after committing a version, create a new version.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-template.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleTemplate.update

Request

Response

204 - Role template version updates successful.

400 - Role template input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to update the role template.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

415 -

429 -

Get role template assignments

GET /v1/role_assignments

Get role template assignments by attributes. The following attributes are supported: `account_id`, `template_id`, `template_version`, `target`, `target_type`, `limit`, `start`. `account_id` is a required query parameter. Only role template assignments with the specified attributes and accessible by the caller are returned. If the caller does not have read access to any role template assignments, an empty array is returned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-assignment.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleAssignment.read

Request

Path Parameters

Query Parameters

account_id

Required *

string

The account GUID in which the role assignment belongs to.

template_id

string

Optional template ID.

template_version

string

Optional role template version.

limit

integer

The number of documents to include in the collection.

start

string

Page token that refers to the page of the collection to return.

Response

200 - role template assignments retrieval successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

assignments

array

List of role assignments.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Create a role template assignment

POST /v1/role_assignments

Assign a role template to child accounts and account groups. This creates the role in the accounts and account groups that you specify.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-assignment.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleAssignment.create

Request

Request Body

RoleAssignmentPrototype

An role assignment to be created.

target

Required *

AssignmentTargetDetails

assignment target account and type

type

Required *

string

Assignment target type

id

Required *

string

ID of the target account

templates

Required *

array

List of role template details for role assignment.

Response

201 - Role assignment creation is successful.

limit

integer

The number of documents to include per each page of the collection.

first

First

Details with linking href to first page of requested collection.

next

Next

Details with href linking to the following page of requested collection.

previous

Previous

Details with linking href to previous page of requested collection.

assignments

array

List of role assignments.

400 - Role assignment input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to create the role assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

409 - A role assignment exists for the given template ID, version, and target account.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

429 -

Retrieve a role assignment

GET /v1/role_assignments/{assignment_id}

Retrieve a role template assignment by providing a role assignment ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-assignment.read

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleAssignment.read

Request

Response

200 - Role assignment retrieval is successful.

id

string

Action control assignment ID.

account_id

string

The account GUID that the role assignments belong to.

href

string

The href URL that links to the role assignments API by role assignment ID.

created_at

string

The UTC timestamp when the role assignment was created.

created_by_id

string

The IAM ID of the entity that created the role assignment.

last_modified_at

string

The UTC timestamp when the role assignment was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role assignment.

operation

string

The current operation of the role assignment

resources

array

Resources created when role template is assigned.

template

RoleAssignmentTemplate

The role template id and version that will be assigned.

target

AssignmentTargetDetails

assignment target account and type

status

string

The role assignment status.

401 -

403 - You do not have access to retrieve the role assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Update a role assignment

PATCH /v1/role_assignments/{assignment_id}

Update a role assignment by providing a role assignment ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-assignment.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleAssignment.update

Request

Request Body

RoleAssignmentPatchTemplate

A role assignment to be created.

template_version

Required *

string

The version number of the template used to identify different versions of same template.

Path Parameters

Query Parameters

Response

200 - Role assignment updates successful.

id

string

Action control assignment ID.

account_id

string

The account GUID that the role assignments belong to.

href

string

The href URL that links to the role assignments API by role assignment ID.

created_at

string

The UTC timestamp when the role assignment was created.

created_by_id

string

The IAM ID of the entity that created the role assignment.

last_modified_at

string

The UTC timestamp when the role assignment was last modified.

last_modified_by_id

string

The IAM ID of the entity that last modified the role assignment.

operation

string

The current operation of the role assignment

resources

array

Resources created when role template is assigned.

template

RoleAssignmentTemplate

The role template id and version that will be assigned.

target

AssignmentTargetDetails

assignment target account and type

status

string

The role assignment status.

401 -

403 - You do not have access to retrieve the role assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

406 -

429 -

Remove a role assignment

DELETE /v1/role_assignments/{assignment_id}

Remove a role template assignment by providing a role assignment ID. You can't delete a role assignment if the status is "in_progress".

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • iam-access-management.role-assignment.delete

Auditing

Calling this method generates the following auditing event.

  • iam-am.roleAssignment.delete

Request

Response

204 - Role assignment deletion successful.

400 - Role assignment was not in valid to delete.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

403 - You do not have access to remove the role assignment.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

404 -

429 -