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

Parameters

accountId

Required *

string

The account GUID that the policies belong to.

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

iamId

string

Optional IAM ID used to identify the subject.

accessGroupId

string

Optional access group id.

type

string

Optional type of policy.

Allowed values: access, authorization

serviceType

string

Optional type of service.

Allowed values: service, platform_service

tagName

string

Optional name of the access tag in the policy.

tagValue

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

Allowed values: type, href, created_at, created_by_id, last_modified_at, last_modified_by_id, state

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.

Allowed values: include_last_permit, display

state

string

The state of the policy.

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

Allowed values: active, deleted

limit

number

The number of documents to include in the collection.

Default: 50

start

string

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

Constraints:

  • Min length: 9
  • Max length: 100
  • Pattern: /^[-A-Za-z0-9+\/]*$/

Response

200 - Policies retrieval successful.

limit

integer

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

first

First

Details with linking href to first page of requested collection.

next

Next

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

previous

Previous

Details with linking href to previous page of requested collection.

policies

array

List of policies.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Create a policy

POST /v1/policies

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

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Authorization

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

  • iam.policy.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.create

Request

Parameters

type

Required *

string

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

Constraints:

  • Min length: 6
  • Max length: 13
  • Pattern: /^[a-z]+$/

subjects

Required *

PolicySubject[]

The subjects associated with a policy.

Constraints:

  • Min items: 1
  • Max items: 1

roles

Required *

PolicyRole[]

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

Constraints:

  • Min items: 1

resources

Required *

PolicyResource[]

The resources associated with a policy.

Constraints:

  • Min items: 1
  • Max items: 1

description

string

Customer-defined description.

Constraints:

  • Min length: 1
  • Max length: 300

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

Response

201 - Policy creation successful.

id

string

The policy ID.

type

string

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

description

string

Customer-defined description

subjects

array

The subjects associated with a policy.

roles

array

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

resources

array

The resources associated with a policy.

href

string

The href links back to the policy.

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

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

state

string

The policy state.

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

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

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

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

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum policies quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Update a policy

PUT /v1/policies/{policy_id}

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

Access

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Authorization

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

  • iam.policy.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.update

Request

Parameters

policyId

Required *

string

The policy ID.

ifMatch

Required *

string

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

type

Required *

string

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

Constraints:

  • Min length: 6
  • Max length: 13
  • Pattern: /^[a-z]+$/

subjects

Required *

PolicySubject[]

The subjects associated with a policy.

Constraints:

  • Min items: 1
  • Max items: 1

roles

Required *

PolicyRole[]

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

Constraints:

  • Min items: 1

resources

Required *

PolicyResource[]

The resources associated with a policy.

Constraints:

  • Min items: 1
  • Max items: 1

description

string

Customer-defined description.

Constraints:

  • Min length: 1
  • Max length: 300

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

Parameters

policyId

Required *

string

The policy ID.

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

Parameters

policyId

Required *

string

The policy ID.

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

Parameters

policyId

Required *

string

The policy ID.

ifMatch

Required *

string

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

state

string

The policy state.

Allowed values: active, deleted

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

Parameters

accountId

Required *

string

The account GUID in which the policies belong to.

Constraints:

  • Min length: 1

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

iamId

string

Optional IAM ID used to identify the subject.

Constraints:

  • Min length: 1

accessGroupId

string

Optional access group id.

Constraints:

  • Min length: 1

type

string

Optional type of policy.

Allowed values: access, authorization

serviceType

string

Optional type of service.

Allowed values: service, platform_service

serviceName

string

Optional name of service.

Constraints:

  • Min length: 1

serviceGroupId

string

Optional ID of service group.

Constraints:

  • Min length: 1

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.

Allowed values: include_last_permit, display

state

string

The state of the policy.

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

Allowed values: active, deleted

limit

number

The number of documents to include in the collection.

Default: 50

start

string

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

Constraints:

  • Min length: 9
  • Max length: 100
  • Pattern: /^[-A-Za-z0-9+\/]*$/

Response

200 - Policies retrieval successful.

limit

integer

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

first

First

Details with linking href to first page of requested collection.

next

Next

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

previous

Previous

Details with linking href to previous page of requested collection.

policies

array

List of policies.

400 - The request you made is not valid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

406 -

429 -

Access

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

Currently, we support two types of patterns:

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

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

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

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

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

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

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Create a policy

POST /v2/policies

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

Access

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

Currently, we support two types of patterns:

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

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

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

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

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

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

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Authorization

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

  • iam.policy.create

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.create

Request

Parameters

control

Required *

Control

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

type

Required *

string

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

Allowed values: access, authorization

description

string

Description of the policy.

Constraints:

  • Min length: 1
  • Max length: 300
  • Pattern: /^.*$/

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

Constraints:

  • Min length: 1
  • Max length: 42
  • Pattern: /^[a-z:-]*$/

rule

V2PolicyRule

Additional access conditions associated with the policy.

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

Response

201 - Policy creation successful.

type

string

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

description

string

Description of the policy.

subject

V2PolicySubject

The subject attributes for whom the policy grants access.

resource

V2PolicyResource

The resource attributes to which the policy grants access.

pattern

string

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

rule

V2PolicyRule

Additional access conditions associated with the policy.

id

string

The policy ID.

href

string

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

control

ControlResponse

created_at

string

The UTC timestamp when the policy was created.

created_by_id

string

The IAM ID of the entity that created the policy.

last_modified_at

string

The UTC timestamp when the policy was last modified.

last_modified_by_id

string

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

state

string

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

last_permit_at

string

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

last_permit_frequency

integer

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

400 - Policy input is invalid.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

401 -

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

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

406 -

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

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

415 -

422 - Exceeded maximum policies quota.

trace

string

The unique transaction ID for the request.

errors

array

The errors encountered during the response.

status_code

integer

The HTTP error code of the response.

429 -

Access

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

Currently, we support two types of patterns:

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

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

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

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

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

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Update a policy

PUT /v2/policies/{id}

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

Access

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

Currently, we support two types of patterns:

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

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

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

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

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

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

Authorization

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

Attribute Operators

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

Attribute Validations

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

Authorization

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

  • iam.policy.update

Auditing

Calling this method generates the following auditing event.

  • iam-am.policy.update

Request

Parameters

id

Required *

string

The policy ID.

Constraints:

  • Min length: 1

ifMatch

Required *

string

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

Constraints:

  • Min length: 1

control

Required *

Control

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

type

Required *

string

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

Allowed values: access, authorization

description

string

Description of the policy.

Constraints:

  • Min length: 1
  • Max length: 300
  • Pattern: /^.*$/

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

Constraints:

  • Min length: 1
  • Max length: 42
  • Pattern: /^[a-z:-]*$/

rule

V2PolicyRule

Additional access conditions associated with the policy.

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

Parameters

id

Required *

string

The policy ID.

Constraints:

  • Min length: 1

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.

Allowed values: include_last_permit, display

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

Parameters

id

Required *

string

The policy ID.

Constraints:

  • Min length: 1

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

Parameters

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

accountId

string

Optional account GUID in which the roles belong to.

serviceName

string

Optional name of IAM enabled service.

Example: iam-groups

sourceServiceName

string

Optional name of source IAM enabled service.

Example: iam-groups

policyType

string

Optional Policy Type.

Example: authorization

serviceGroupId

string

Optional id of service group.

Example: IAM

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

Parameters

displayName

Required *

string

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

Constraints:

  • Min length: 1
  • Max length: 50

actions

Required *

string[]

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

Constraints:

  • Min items: 1

name

Required *

string

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

Example: Developer

Constraints:

  • Min length: 1
  • Max length: 30
  • Pattern: /^[A-Z]{1}[A-Za-z0-9]{0,29}$/

accountId

Required *

string

The account GUID.

serviceName

Required *

string

The service name.

Example: iam-groups

description

string

The description of the role.

Constraints:

  • Min length: 1
  • Max length: 250

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

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

Parameters

roleId

Required *

string

The role ID.

ifMatch

Required *

string

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

displayName

Required *

string

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

Constraints:

  • Min length: 1
  • Max length: 50

actions

Required *

string[]

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

Constraints:

  • Min items: 1

description

string

The description of the role.

Constraints:

  • Min length: 1
  • Max length: 250

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

Parameters

roleId

Required *

string

The role ID.

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

Parameters

roleId

Required *

string

The role ID.

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

Parameters

accountId

Required *

string

The account GUID that the policy templates belong to.

Constraints:

  • Min length: 1
  • Max length: 32
  • Pattern: /^[A-Za-z0-9-]*$/

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

state

string

The policy template state.

Allowed values: active, deleted

name

string

The policy template name.

Constraints:

  • Min length: 1
  • Max length: 100

policyServiceType

string

Service type, Optional.

Allowed values: service, platform_service

policyServiceName

string

Service name, Optional.

Constraints:

  • Min length: 1

policyServiceGroupId

string

Service group id, Optional.

Constraints:

  • Min length: 1

policyType

string

Policy type, Optional.

Allowed values: access, authorization

limit

number

The number of documents to include in the collection.

Default: 50

start

string

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

Constraints:

  • Min length: 9
  • Max length: 100
  • Pattern: /^[-A-Za-z0-9+\/]*$/

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

Parameters

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.

Constraints:

  • Min length: 1
  • Max length: 100
  • Pattern: /^.*$/

accountId

Required *

string

Enterprise account ID where this template is created.

Constraints:

  • Min length: 1
  • Max length: 32
  • Pattern: /^[A-Za-z0-9-]*$/

policy

Required *

TemplatePolicy

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

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.

Constraints:

  • Max length: 300
  • Pattern: /^.*$/

committed

boolean

Committed status of the template.

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

state

string

The policy template state.

Allowed values: active, deleted

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

policy

Required *

TemplatePolicy

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

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.

Constraints:

  • Min length: 1
  • Max length: 100
  • Pattern: /^.*$/

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.

Constraints:

  • Max length: 300
  • Pattern: /^.*$/

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

state

string

The policy template state.

Allowed values: active, deleted

limit

number

The number of documents to include in the collection.

Default: 50

start

string

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

Constraints:

  • Min length: 9
  • Max length: 100
  • Pattern: /^[-A-Za-z0-9+\/]*$/

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

version

Required *

string

The policy template version.

Constraints:

  • Min length: 1
  • Max length: 2
  • Pattern: /^[0-9]*$/

ifMatch

Required *

string

The revision number for updating a policy template version and must match the Etag value of the existing policy template version. The Etag can be retrieved using the GET /v1/policy_templates/{policy_template_id}/versions/{version} API and looking at the Etag response header.

Constraints:

  • Min length: 1

policy

Required *

TemplatePolicy

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

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.

Constraints:

  • Min length: 1
  • Max length: 100
  • Pattern: /^.*$/

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.

Constraints:

  • Max length: 300
  • Pattern: /^.*$/

committed

boolean

Committed status of the template version.

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

version

Required *

string

The policy template version.

Constraints:

  • Min length: 1
  • Max length: 2
  • Pattern: /^[0-9]*$/

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

version

Required *

string

The policy template version.

Constraints:

  • Min length: 1
  • Max length: 2
  • Pattern: /^[0-9]*$/

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

Parameters

policyTemplateId

Required *

string

The policy template ID.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

version

Required *

string

The policy template version.

Constraints:

  • Min length: 1
  • Max length: 2
  • Pattern: /^[0-9]*$/

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

Parameters

version

Required *

string

specify version of response body format.

Constraints:

  • Min length: 1

accountId

Required *

string

The account GUID in which the policies belong to.

Constraints:

  • Min length: 1
  • Max length: 32
  • Pattern: /^[A-Za-z0-9-]*$/

acceptLanguage

string

Language code for translations

  • `default` - English
  • `de` - German (Standard)
  • `en` - English
  • `es` - Spanish (Spain)
  • `fr` - French (Standard)
  • `it` - Italian (Standard)
  • `ja` - Japanese
  • `ko` - Korean
  • `pt-br` - Portuguese (Brazil)
  • `zh-cn` - Chinese (Simplified, PRC)
  • `zh-tw` - (Chinese, Taiwan).

Default: default

Constraints:

  • Min length: 1

templateId

string

Optional template id.

Constraints:

  • Min length: 1
  • Max length: 51
  • Pattern: /^policyTemplate-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

templateVersion

string

Optional policy template version.

Constraints:

  • Min length: 1
  • Max length: 2
  • Pattern: /^[0-9]*$/

limit

number

The number of documents to include in the collection.

Default: 50

start

string

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

Constraints:

  • Min length: 9
  • Max length: 100
  • Pattern: /^[-A-Za-z0-9+\/]*$/

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 -

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

Parameters

assignmentId

Required *

string

The policy template assignment ID.

Constraints:

  • Min length: 1
  • Max length: 53

version

Required *

string

specify version of response body format.

Constraints:

  • Min length: 1

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 -