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 -
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 -
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 -
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:
- `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.
- `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:
- `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.
- `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 -
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:
- `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.
- `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:
- `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.
- `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 -
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.