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 -
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 -
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 -
To create an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.
Currently, we support two types of patterns:
- `time-based`: Used to specify a time-based restriction
Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ```
The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.
- `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.
Combine conditions to specify an attribute-based condition using AND/OR-based operators.
For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```
In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.
Authorization
Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use `"type": "authorization"` in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the `accountId` attributes. The policy subject must include either `serviceName` or `resourceGroupId` (or both) attributes.
Attribute Operators
Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.
Attribute Validations
Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations. ">
Create a policy
POST /v2/policies
Creates a policy to grant access between a subject and a resource. Currently, there is one type of a v2/policy: access. A policy administrator might want to create an access policy that grants access to a user, service-id, or an access group.
Access
To create an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.
Currently, we support two types of patterns:
- `time-based`: Used to specify a time-based restriction
Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ```
The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.
- `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.
Combine conditions to specify an attribute-based condition using AND/OR-based operators.
For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```
In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.
Authorization
Authorization policies are supported by services on a case by case basis. Refer to service documentation to verify their support of authorization policies. To create an authorization policy, use `"type": "authorization"` in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the `accountId` attributes. The policy subject must include either `serviceName` or `resourceGroupId` (or both) attributes.
Attribute Operators
Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.
Attribute Validations
Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
iam.policy.create
Auditing
Calling this method generates the following auditing event.
iam-am.policy.create
Request
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 -
To update an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.
Currently, we support two types of patterns:
- `time-based`: Used to specify a time-based restriction
Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ``` The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.
- `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.
Combine conditions to specify an attribute-based condition using AND/OR-based operators.
For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```
In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.
Authorization
To update an authorization policy, use `"type": "authorization"` in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the `accountId` attributes. The policy subject must include either `serviceName` or `resourceGroupId` (or both) attributes.
Attribute Operators
Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.
Attribute Validations
Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations. ">
Update a policy
PUT /v2/policies/{id}
Update a policy to grant access between a subject and a resource. A policy administrator might want to update an existing policy.
Access
To update an access policy, use `"type": "access"` in the body. The supported subject attributes are `iam_id` and `access_group_id`. Use the `iam_id` subject attribute to assign access to a user or service-id. Use the `access_group_id` subject attribute to assign access to an access group. Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. The policy resource must include either the `serviceType`, `serviceName`, `resourceGroupId` or `service_group_id` attribute and the `accountId` attribute. In the rule field, you can specify a single condition by using `key`, `value`, and condition `operator`, or a set of `conditions` with a combination `operator`. The possible combination operators are `and` and `or`.
Currently, we support two types of patterns:
- `time-based`: Used to specify a time-based restriction
Combine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week). For example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule: ```json "rule": { "operator": "and", "conditions": [{ "key": "", "operator": "dayOfWeekAnyOf", "value": ["1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00"] }, "key": "", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, "key": "", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" }] } ``` You can use the following operators in the `key` and `value` pair: ``` 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals', 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals', 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals', 'dayOfWeekEquals', 'dayOfWeekAnyOf' ``` The pattern field that matches the rule is required when rule is provided. For the business hour rule example above, the `pattern` is `"time-based-conditions:weekly"`. For more information, see Time-based conditions operators and Limiting access with time-based conditions. If the subject is a locked service-id, the request will fail.
- `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.
Combine conditions to specify an attribute-based condition using AND/OR-based operators.
For example, a policy can grant access based on multiple conditions applied on the resource attributes below: ```json "pattern": "attribute-based-condition:resource:literal-and-wildcard" "rule": { "operator": "or", "conditions": [ { "operator": "and", "conditions": [ { "key": "", "operator": "stringEquals", "value": "home/test" }, { "key": "", "operator": "stringEquals", "value": "/" } ] }, { "key": "", "operator": "stringMatch", "value": "home/David/*" } ] } ```
In addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` OR the `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, making policies easier to administer and stay within the policy limit for an account. View the list of operators that can be used in the condition here.
Authorization
To update an authorization policy, use `"type": "authorization"` in the body. The subject attributes must match the supported authorization subjects of the resource. Multiple subject attributes might be provided. The following attributes are supported: serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId Assign roles that are supported by the service or platform roles. For more information, see IAM roles and actions. The user must also have the same level of access or greater to the target resource in order to grant the role. Use only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the documentation. Both the policy subject and the policy resource must include the `accountId` attributes. The policy subject must include either `serviceName` or `resourceGroupId` (or both) attributes.
Attribute Operators
Currently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available. For more information, see Assigning access by using wildcard policies.
Attribute Validations
Policy attribute values must be between 1 and 1,000 characters in length. If location related attributes like geography, country, metro, region, satellite, and locationvalues are supported by the service, they are validated against Global Catalog locations.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
iam.policy.update
Auditing
Calling this method generates the following auditing event.
iam-am.policy.update
Request
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.