{ "openapi": "3.0.0", "info": { "version": "1.0.1", "title": "IAM Policy Management", "x-ibm-name": "policy-management-api", "x-alternate-name": "iam_policy_management", "description": " \n\n## Introduction\n\nWith the IBM Cloud® Identity and Access Management (IAM) Policy Management API, you can create, update, view, and delete IAM policies. An IAM policy enables a subject to access a resource. These policies are used in access decisions when you call APIs for IAM-enabled services. For more information about how access management works, see [Managing access in IBM Cloud](https://cloud.ibm.com/docs/account?topic=account-cloudaccess).\n\nThere are three primary values in a policy: a subject, roles, and resources.\n\nThe subject is who or what is being granted access. The subject can be an IAM ID or an access group ID. The IAM ID is the ID of the entity that you are giving access to. The value can be a user or a service ID. The access group ID is the ID of the access group. An access group contains a set of users or service IDs. Access groups are the preferred method of managing access control. For more information, see [Setting up access groups](https://cloud.ibm.com/docs/iam?topic=iam-groups).\n\nThe following table shows the example formats for the supported subject types:\n\nType | Attribute name | Attribute value |\n------------ | ------------- | ------------- |\nUser | iam_id | `IBMid-123456...` | \nService ID | iam_id | `iam-ServiceId-12345...` |\nAccess group | access_group_id | `AccessGroupId-12345...` |\n\nThe second value in a policy in the role. A role is a collection of actions that can be taken on a resource. There are platform, service, and custom roles. For more information, see [IAM roles](https://cloud.ibm.com/docs/account?topic=account-userroles#iamusermanrol). And, the final value of the policy is the targeted resources whether it's an entire service, resource group, or specific service instance.\n\nTwo types of policies are supported: access policies and authorization policies. For more information, see [Create a policy](https://cloud.ibm.com/apidocs/iam-policy-management#create-a-policy).\n\nWith policy templates and assignments you can centrally manage the policies for child accounts in your organization from the root enterprise account. For more information, see [Working with template versions](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-working-with-versions&interface=ui) and [Best practices for assigning access in an enterprise](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-access-enterprises).\n\nSDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the [IBM Cloud SDK Common project](https://github.com/IBM/ibm-cloud-sdk-common) on GitHub.\n\nInstalling the Go SDK\n\nGo modules (recommended): Add the following import in your code, and then run `go build` or `go mod tidy`\n\n```go\nimport (\n\t\"github.com/IBM/platform-services-go-sdk/iampolicymanagementv1\"\n)\n```\n\nGo get\n\n```bash\ngo get -u github.com/IBM/platform-services-go-sdk/iampolicymanagementv1\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-go-sdk](https://github.com/IBM/platform-services-go-sdk)\n\nInstalling the Java SDK\n\nMaven\n\n```xml\n\n\tcom.ibm.cloud\n\tiam-policy-management\n\t{version}\n\n```\n\nGradle\n\n```bash\ncompile 'com.ibm.cloud:iam-policy-management:{version}'\n```\n\nReplace `{version}` in these examples with the release version.\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-java-sdk](https://github.com/IBM/platform-services-java-sdk)\n\nInstalling the Node SDK\n\n```bash\nnpm install ibm-platform-services\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-node-sdk](https://github.com/IBM/platform-services-node-sdk)\n\nInstalling the Python SDK\n\n```bash\npip install --upgrade \"ibm-platform-services\"\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-python-sdk](https://github.com/IBM/platform-services-python-sdk)\n\n## Endpoint URLs\n\nThe IAM Policy Management API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.\n\n```\nhttps://iam.cloud.ibm.com\n```\n\nIf you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see [Enabling VRF and service endpoints](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint).\n\n* Private endpoint URL for VPC infrastructure: `https://private.iam.cloud.ibm.com`\n* Private endpoint URLs for classic infrastructure:\n * Sydney: `https://private.au-syd.iam.cloud.ibm.com`\n * Sao Paulo: `https://private.br-sao.iam.cloud.ibm.com`\n * Montreal: `https://private.ca-mon.iam.cloud.ibm.com`\n * Toronto: `https://private.ca-tor.iam.cloud.ibm.com`\n * Frankfurt DC: `https://private.eu-de.iam.cloud.ibm.com`\n * London: `https://private.eu-gb.iam.cloud.ibm.com`\n * Madrid: `https://private.eu-es.iam.cloud.ibm.com`\n * Tokyo: `https://private.jp-tok.iam.cloud.ibm.com`\n * Osaka: `https://private.jp-osa.iam.cloud.ibm.com`\n * Washington DC: `https://private.us-east.iam.cloud.ibm.com`\n * Dallas: `https://private.us-south.iam.cloud.ibm.com`\n\n## Authentication\n\nAuthorization to the IAM Policy Management API is enforced by using an IBM Cloud IAM access token. The token is used to to determine the actions that a user or service ID has access to when they use the API. \n\nObtaining an IAM token for an authenticated user or service ID is described in the [IAM Identity Services API](https://cloud.ibm.com/apidocs/iam-identity-token-api) documentation. \n\nTo use the API, add a valid IAM token to the HTTP Authorization request header, for example, `-H 'Authorization: Bearer '`.\n\nWhen you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:\n- Programmatically by constructing an IAM authenticator instance and supplying your IAM API key \n- By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key\n\nIn this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.\n\nFor more information, see the Authentication section of the [IBM Cloud SDK Common](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md) documentation.\n\nAny access, such as IAM actions, that is required to call a method is listed per individual method. The IAM actions associated with basic tasks for working with policies, including create, update, and delete actions, are inherited by the platform roles that can be assigned for each IAM-enabled service. For more information about the required IAM actions for custom roles and how they map to the access roles, see the list of actions and roles for the [role management service](https://cloud.ibm.com/docs/account?topic=account-account-services#custom-roles-account-management).\n\nTo retrieve your access token:\n\n```bash\ncurl -X POST \\\n \"https://iam.cloud.ibm.com/identity/token\" \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --header 'Accept: application/json' \\\n --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \\\n --data-urlencode 'apikey='\n```\n\nReplace `` with your IAM API key.\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport IAM_POLICY_MANAGEMENT_URL=\nexport IAM_POLICY_MANAGEMENT_AUTHTYPE=iam\nexport IAM_POLICY_MANAGEMENT_APIKEY=\n```\n\nExample of constructing the service client\n```go\nimport {\n \"github.com/IBM/platform-services-go-sdk/iampolicymanagementv1\"\n}\n...\nserviceClientOptions := &iampolicymanagementv1.IamPolicyManagementV1Options{}\nserviceClient, err := iampolicymanagementv1.NewIamPolicyManagementV1UsingExternalConfig(serviceClientOptions)\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport IAM_POLICY_MANAGEMENT_URL=\nexport IAM_POLICY_MANAGEMENT_AUTHTYPE=iam\nexport IAM_POLICY_MANAGEMENT_APIKEY=\n```\n\nExample of constructing the service client\n```java\nimport com.ibm.cloud.platform_services.iam_policy_management.v1.IamPolicyManagement;\n...\nIamPolicyManagement serviceClient = IamPolicyManagement.newInstance();\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport IAM_POLICY_MANAGEMENT_URL=\nexport IAM_POLICY_MANAGEMENT_AUTHTYPE=iam\nexport IAM_POLICY_MANAGEMENT_APIKEY=\n```\n\nExample of constructing the service client\n```javascript\nconst IamPolicyManagementV1 = require('ibm-platform-services/iam-policy-management/v1');\n...\nconst serviceClient = IamPolicyManagementV1.newInstance({});\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport IAM_POLICY_MANAGEMENT_URL=\nexport IAM_POLICY_MANAGEMENT_AUTHTYPE=iam\nexport IAM_POLICY_MANAGEMENT_APIKEY=\n```\n\nExample of constructing the service client\n```python\nfrom ibm_platform_services import IamPolicyManagementV1\n...\nservice_client = IamPolicyManagementV1.new_instance()\n```\n\n## Auditing\n\nYou can monitor API activity within your account by using the IBM Cloud® Activity Tracker service. You can track when specific API methods are called by reviewing generated events in Activity Tracker.\n\nIf an event is tracked for a method, you can find it listed with the method. For more information about how to track IAM activity, see [Auditing events for IAM](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-at_events_iam).\n\n## Error handling\n\nThe Policy Management APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows:\n```json\n{\n \"trace\": \"cd4f7573121a4cf99f0079f8482b3d6b\",\n \"errors\": [\n {\n \"code\": \"invalid_token\",\n \"message\": \"The provided IAM token is invalid.\"\n }\n ],\n \"status_code\": 401\n}\n```\nIf an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations that are defined in the `Reference` section describe example errors that can be returned from a failed request. All responses from the IAM Policy Management API are in the JSON format.\n\nHere are potential error codes that the API can return.\n\n| HTTP Error Code | Description | Recovery |\n|-----------------|-------------|----------|\n| `200` | Success | The request was successful. |\n| `201` | Created | The resource was successfully created. |\n| `204` | No Content | The request was successful. No response body is provided. |\n| `400` | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. |\n| `401` | Unauthorized | You are not authorized to make this request. The token is either invalid, missing or expired. Get a new valid token and try again. |\n| `403` | Forbidden | The token is valid, but the subject of the token is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions. |\n| `404` | Not Found | The requested resource can't be found. |\n| `409` | Conflict | The entity is already in the requested state. |\n| `415` | Unsupported Media Type | Request body sent was formatted by using an unsupported media type. |\n| `429` | Too Many Requests | Too many requests have been made within a given time window. Wait the time in seconds indicated in the `Retry-After` response header before calling the API again. |\n| `500` | Service Unavailable | IAM Policy Management Point is currently unavailable. Your request can't be processed. Wait a few minutes and try again. |\n\n## Additional headers\n\nSome additional headers might be required to make successful requests to the API.\nThose additional headers are:\n\n### Transaction-Id\nAn optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services by using one identifier. The header key must be set to `Transaction-Id` and the value is anything that you choose.\n\nIf no transaction ID is passed in, then a random ID is generated.\n\n## Sorting\n\nSorting is available on the policies listing APIs. Use a `sort` query parameter set to the field name you want the results sorted by. All the top level policy fields are supported.\n\nTo reverse sort, add a `-` prefix to the field name.\n\nFor example, for the GET /v1/policies endpoint, a query parameter of `sort=last_modified_at` sorts the returned policies in ascending date and time order by last_modified_at. Meanwhile a query parameter of `sort=-last_modified_at` returns the policies in descending date and time order by last_modified_at.\n\n## Policy data enrichment\n\nCurrently two options are available: `display` and `include_last_permit`. By including query parameter `format=display`, the API returns the list of all actions included in each of the policy roles. \n\n```json\n\"roles\": [\n {\n \"role_id\": \"crn:v1:bluemix:public:iam::::role:Administrator\",\n \"display_name\": \"Administrator\",\n \"description\": \"Administrators can change object metadata or visibility for private services added to the account and can restrict the visibility of a public service.\",\n \"actions\": [\n {\n \"id\": \"global-search-tagging.resource.read\",\n \"displayName\": \"Find cloud resources\",\n \"description\": \"The ability to find the resource using Global Search and Tagging search API.\"\n },\n {\n \"id\": \"iam.policy.read\",\n \"displayName\": \"IAM Policy Read\",\n \"description\": \"The ability to see policies.\"\n },\n {\n \"id\": \"iam.policy.create\",\n \"displayName\": \"IAM Policy Create\",\n \"description\": \"The ability to create policies.\"\n }\n ]\n }\n ],\n```\n\nIncluding the query parameter `format=include_last_permit` returns details of when the policy last granted a permit decision and the number of times it has done so. \n\n```json\n{\n \"id\": \"03b5696c-6844-430f-a3b1-8f2d0de53218\",\n \"type\": \"access\",\n \"subjects\": ...,\n \"roles\": ...,\n \"resources\": ...,\n \"last_permit_at\": \"2020-10-16T22:17:40.832Z\",\n \"last_permit_frequency\": 18\n},\n```\n\nThis data is provided for informational purposes only. The last permit data only include records begining from end of October 2020.\n\n## Rate limiting\n\nA response with status `429 Too Many Requests` is returned if too many requests are made within a time window. The response includes a `Retry-After` header to indicate the time in seconds to wait before sending the next request.\n\n## Related APIs\n\nWhen you work with the Policy Management API, it might be helpful to be aware of other IAM services. See Identity Services to learn about API key, service ID, and token creation. See Access groups to create groups and manage memberships.\n\n* [IAM Access Groups](https://cloud.ibm.com/apidocs/iam-access-groups)\n* [IAM Identity Service](https://cloud.ibm.com/apidocs/iam-identity-token-api)", "contact": { "name": "Carlos", "email": "cfgomez@us.ibm.com" }, "x-codegen-config": { "java": { "apiPackage": "com.ibm.cloud.platform_services" }, "go": { "apiPackage": "github.com/IBM/platform-services-go-sdk", "improvedNameFormattingV2": true }, "python": { "apiPackage": "ibm_platform_services" } }, "x-sdk-supported-languages": [ "go", "java", "node", "python" ], "x-github": "https://github.ibm.com/cloud-api-docs/iam-access-management", "x-github-issues": "https://github.ibm.com/cloud-api-docs/iam-access-management/issues/new", "x-last-updated": "2023-09-08" }, "tags": [ { "name": "Policies", "description": "Policy Management rest api." }, { "name": "Roles", "description": "Policy Management roles." }, { "name": "v2/Policies", "description": "Policy Management rest api for v2/policies" }, { "name": "Policy templates", "description": "Policy Templates Management rest api." }, { "name": "Policy assignments", "description": "Policy Assignments Management rest api." }, { "name": "Access Management Settings", "description": "Access Management Settings rest API." }, { "name": "Action Control Templates", "description": "Action Control Templates management rest api." }, { "name": "Action Control Assignments", "description": "Action Control Assignments management rest api." }, { "name": "Role Templates", "description": "Role Templates management rest api." }, { "name": "Role Assignments", "description": "Role Assignments management rest api." } ], "security": [ { "IAM": [] } ], "servers": [ { "url": "https://iam.cloud.ibm.com" } ], "paths": { "/v1/policies": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Policies" ], "summary": "Get policies by attributes", "operationId": "list_policies", "description": "Get policies and filter by attributes.\nWhile managing policies, you might want to retrieve\npolicies in the account and filter by attribute values.\nThis can be done through query parameters.\nThe following attributes are supported:\naccount_id, iam_id, access_group_id, type, service_type, sort, format and state.\naccount_id is a required query parameter.\nOnly policies that have the specified attributes and that\nthe caller has read access to are returned.\nIf the caller does not have read access to any policies an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID that the policies belong to.", "schema": { "type": "string" } }, { "name": "iam_id", "in": "query", "description": "Optional IAM ID used to identify the subject.", "schema": { "type": "string" } }, { "name": "access_group_id", "in": "query", "description": "Optional access group id.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Optional type of policy.", "schema": { "type": "string", "enum": [ "access", "authorization" ] } }, { "name": "service_type", "in": "query", "description": "Optional type of service.", "schema": { "type": "string", "enum": [ "service", "platform_service" ] } }, { "name": "tag_name", "in": "query", "description": "Optional name of the access tag in the policy.", "schema": { "type": "string" } }, { "name": "tag_value", "in": "query", "description": "Optional value of the access tag in the policy.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field. Example '-last_modified_at'", "schema": { "type": "string", "enum": [ "type", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "state" ] } }, { "name": "format", "in": "query", "description": "Include additional data per policy returned\n* `include_last_permit` - returns details of when the policy last granted a permit decision and the number of times it has done so\n* `display` - returns the list of all actions included in each of the policy roles", "schema": { "type": "string", "enum": [ "include_last_permit", "display" ] } }, { "name": "state", "in": "query", "description": "The state of the policy.\n* `active` - returns active policies\n* `deleted` - returns non-active policies", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Policies retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCollection" }, "examples": { "response": { "value": { "policies": [ { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of SERVICE_NAME in the account.", "subjects": [ { "attributes": [ { "name": "iam_id", "value": "IBMid-123453user" } ] } ], "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "resources": [ { "attributes": [ { "name": "accountId", "value": "ACCOUNT_ID", "operator": "stringEquals" }, { "name": "serviceName", "value": "SERVICE_NAME", "operator": "stringEquals" } ] } ], "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policies?account_id=$ACCOUNT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewListPoliciesOptions(\n", " exampleAccountID,\n", ")\n", "options.SetIamID(exampleUserID)\n", "options.SetFormat(\"include_last_permit\")\n", "\n", "policyList, response, err := iamPolicyManagementService.ListPolicies(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyList, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListPoliciesOptions options = new ListPoliciesOptions.Builder()\n", " .accountId(exampleAccountId)\n", " .iamId(EXAMPLE_USER_ID)\n", " .format(\"include_last_permit\")\n", " .build();\n", "\n", "Response response = service.listPolicies(options).execute();\n", "PolicyCollection policyCollection = response.getResult();\n", "\n", "System.out.println(policyCollection);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " accountId: exampleAccountId,\n", " iamId: exampleUserId,\n", " format: 'include_last_permit',\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.listPolicies(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy_list = iam_policy_management_service.list_policies(\n", " account_id=example_account_id, iam_id=example_user_id, format='include_last_permit'\n", ").get_result()\n", "\n", "print(json.dumps(policy_list, indent=2))" ] } ] } ] } } }, "post": { "tags": [ "Policies" ], "summary": "Create a policy", "operationId": "create_policy", "description": "Creates a policy to grant access between a subject and a resource.\nThere are two types of policies: **access** and **authorization**.\nA policy administrator might want to create an access policy\nwhich grants access to a user, service-id, or an access group.\nThey might also want to create an authorization policy and setup\naccess between services.\n\n### Access\n\nTo create an access policy, use **`\"type\": \"access\"`** in the body.\nThe possible subject attributes are **`iam_id`** and **`access_group_id`**.\nUse the **`iam_id`** subject attribute for assigning access for a user or service-id.\nUse the **`access_group_id`** subject attribute for assigning access for an access group.\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nThe policy resource must include either the **`serviceType`**, **`serviceName`**, **`resourceGroupId`** or **`service_group_id`** attribute and the **`accountId`** attribute.\nThe 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.\nIf the subject is a locked service-id, the request will fail.\n\n### Authorization\n\nAuthorization policies are supported by services on a case by case basis.\nRefer to service documentation to verify their support of authorization policies.\nTo create an authorization policy, use **`\"type\": \"authorization\"`** in the body.\nThe subject attributes must match the supported authorization subjects of the resource.\nMultiple subject attributes might be provided. The following attributes are supported:\n serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nThe user must also have the same level of access or greater to the target resource in order to grant the role.\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nBoth the policy subject and the policy resource must include the **`accountId`** attributes. The policy subject must include either **`serviceName`** or **`resourceGroupId`** (or both) attributes.\n\n### Attribute Operators\n\nCurrently, only the `stringEquals` and the `stringMatch` operators are available. Resource attributes may support one or both operators.\nFor more information, see [Assigning access by using wildcard policies](https://cloud.ibm.com/docs/account?topic=account-wildcard).\n\n### Attribute Validations\n\nPolicy 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.\n", "x-codegen-request-body-name": "policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRequest" } } }, "description": "A policy to be created.", "required": true }, "responses": { "201": { "description": "Policy creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of SERVICE_NAME in the account.", "subjects": [ { "attributes": [ { "name": "iam_id", "value": "IBMid-123453user" } ] } ], "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "resources": [ { "attributes": [ { "name": "accountId", "value": "ACCOUNT_ID", "operator": "stringEquals" }, { "name": "serviceName", "value": "SERVICE_NAME", "operator": "stringEquals" } ], "tags": [ { "name": "project", "value": "moonshot", "operator": "stringEquals" }, { "name": "pipeline", "value": "test", "operator": "stringEquals" } ] } ], "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "400": { "description": "Policy input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to create policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum policies quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum policies quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/policies' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"type\": \"access\",\n", " \"description\": \"Editor role for SERVICE_NAME\\'s RESOURCE_NAME\",\n", " \"subjects\": [\n", " {\n", " \"attributes\": [\n", " {\n", " \"name\": \"iam_id\",\n", " \"value\": \"IBMid-123453user\"\n", " }\n", " ]\n", " }\n", " ],\n", " \"roles\":[\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Editor\"\n", " }\n", " ],\n", " \"resources\":[\n", " {\n", " \"attributes\": [\n", " {\n", " \"name\": \"accountId\",\n", " \"value\": \"$ACCOUNT_ID\"\n", " },\n", " {\n", " \"name\": \"serviceName\",\n", " \"value\": \"$SERVICE_NAME\"\n", " },\n", " {\n", " \"name\": \"resource\",\n", " \"value\": \"$RESOURCE_NAME\",\n", " \"operator\": \"stringEquals\"\n", " }\n", " ]\n", " }\n", " ]\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "subjectAttribute := &iampolicymanagementv1.SubjectAttribute{\n", " Name: core.StringPtr(\"iam_id\"),\n", " Value: &exampleUserID,\n", "}\n", "policySubjects := &iampolicymanagementv1.PolicySubject{\n", " Attributes: []iampolicymanagementv1.SubjectAttribute{*subjectAttribute},\n", "}\n", "policyRoles := &iampolicymanagementv1.PolicyRole{\n", " RoleID: core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Viewer\"),\n", "}\n", "accountIDResourceAttribute := &iampolicymanagementv1.ResourceAttribute{\n", " Name: core.StringPtr(\"accountId\"),\n", " Value: core.StringPtr(exampleAccountID),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.ResourceAttribute{\n", " Name: core.StringPtr(\"serviceType\"),\n", " Value: core.StringPtr(\"service\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "policyResourceTag := &iampolicymanagementv1.ResourceTag{\n", " Name: core.StringPtr(\"project\"),\n", " Value: core.StringPtr(\"prototype\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "policyResources := &iampolicymanagementv1.PolicyResource{\n", " Attributes: []iampolicymanagementv1.ResourceAttribute{\n", " *accountIDResourceAttribute, *serviceNameResourceAttribute},\n", " Tags: []iampolicymanagementv1.ResourceTag{*policyResourceTag},\n", "}\n", "\n", "options := iamPolicyManagementService.NewCreatePolicyOptions(\n", " \"access\",\n", " []iampolicymanagementv1.PolicySubject{*policySubjects},\n", " []iampolicymanagementv1.PolicyRole{*policyRoles},\n", " []iampolicymanagementv1.PolicyResource{*policyResources},\n", ")\n", "\n", "policy, response, err := iamPolicyManagementService.CreatePolicy(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "examplePolicyID = *policy.ID\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "SubjectAttribute subjectAttribute = new SubjectAttribute.Builder()\n", " .name(\"iam_id\")\n", " .value(EXAMPLE_USER_ID)\n", " .build();\n", "\n", "PolicySubject policySubjects = new PolicySubject.Builder()\n", " .addAttributes(subjectAttribute)\n", " .build();\n", "\n", "PolicyRole policyRoles = new PolicyRole.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Viewer\")\n", " .build();\n", "\n", "ResourceAttribute accountIdResourceAttribute = new ResourceAttribute.Builder()\n", " .name(\"accountId\")\n", " .value(exampleAccountId)\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "ResourceAttribute serviceNameResourceAttribute = new ResourceAttribute.Builder()\n", " .name(\"serviceType\")\n", " .value(\"service\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "ResourceTag policyResourceTag = new ResourceTag.Builder()\n", " .name(\"project\")\n", " .value(\"prototype\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "PolicyResource policyResources = new PolicyResource.Builder()\n", " .addAttributes(accountIdResourceAttribute)\n", " .addAttributes(serviceNameResourceAttribute)\n", " .addTags(policyResourceTag)\n", " .build();\n", "\n", "CreatePolicyOptions options = new CreatePolicyOptions.Builder()\n", " .type(\"access\")\n", " .subjects(Arrays.asList(policySubjects))\n", " .roles(Arrays.asList(policyRoles))\n", " .resources(Arrays.asList(policyResources))\n", " .build();\n", "\n", "Response response = service.createPolicy(options).execute();\n", "Policy policy = response.getResult();\n", "\n", "examplePolicyId = policy.getId();\n", "\n", "System.out.println(policy);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const policySubjects = [\n", " {\n", " attributes: [\n", " {\n", " name: 'iam_id',\n", " value: exampleUserId,\n", " },\n", " ],\n", " },\n", "];\n", "const policyRoles = [\n", " {\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Viewer',\n", " },\n", "];\n", "const accountIdResourceAttribute = {\n", " name: 'accountId',\n", " value: exampleAccountId,\n", " operator: 'stringEquals',\n", "};\n", "const serviceNameResourceAttribute = {\n", " name: 'serviceType',\n", " value: 'service',\n", " operator: 'stringEquals',\n", "};\n", "const policyResourceTag = {\n", " name: 'project',\n", " operator: 'stringEquals',\n", " value: 'prototype',\n", "};\n", "const policyResources = [\n", " {\n", " attributes: [accountIdResourceAttribute, serviceNameResourceAttribute],\n", " tags: [policyResourceTag],\n", " },\n", "];\n", "const params = {\n", " type: 'access',\n", " subjects: policySubjects,\n", " roles: policyRoles,\n", " resources: policyResources,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.createPolicy(params);\n", " examplePolicyId = res.result.id;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy_subjects = PolicySubject(attributes=[SubjectAttribute(name='iam_id', value=example_user_id)])\n", "policy_roles = PolicyRole(role_id='crn:v1:bluemix:public:iam::::role:Viewer')\n", "account_id_resource_attribute = ResourceAttribute(name='accountId', value=example_account_id)\n", "service_name_resource_attribute = ResourceAttribute(name='serviceType', value='service')\n", "policy_resource_tag = ResourceTag(name='project', value='prototype')\n", "policy_resources = PolicyResource(\n", " attributes=[account_id_resource_attribute, service_name_resource_attribute], tags=[policy_resource_tag]\n", ")\n", "\n", "policy = iam_policy_management_service.create_policy(\n", " type='access', subjects=[policy_subjects], roles=[policy_roles], resources=[policy_resources]\n", ").get_result()\n", "\n", "global example_policy_id\n", "example_policy_id = policy['id']\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } } }, "/v1/policies/{policy_id}": { "parameters": [ { "name": "policy_id", "in": "path", "required": true, "description": "The policy ID.", "schema": { "type": "string" } } ], "put": { "tags": [ "Policies" ], "summary": "Update a policy", "operationId": "replace_policy", "description": "Update a policy to grant access between a subject and a resource.\nA policy administrator might want to update an existing policy.\nThe policy type cannot be changed (You cannot change an access policy to an authorization policy).\n\n### Access\n\nTo update an access policy, use **`\"type\": \"access\"`** in the body.\nThe possible subject attributes are **`iam_id`** and **`access_group_id`**.\nUse the **`iam_id`** subject attribute for assigning access for a user or service-id.\nUse the **`access_group_id`** subject attribute for assigning access for an access group.\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nThe policy resource must include either the **`serviceType`**, **`serviceName`**, or **`resourceGroupId`** attribute and the **`accountId`** attribute.`\nIf the subject is a locked service-id, the request will fail.\n\n### Authorization\n\nTo update an authorization policy, use **`\"type\": \"authorization\"`** in the body.\nThe subject attributes must match the supported authorization subjects of the resource.\nMultiple subject attributes might be provided. The following attributes are supported:\n serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nThe user must also have the same level of access or greater to the target resource in order to grant the role.\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nBoth the policy subject and the policy resource must include the **`accountId`** attributes. The policy subject must include either **`serviceName`** or **`resourceGroupId`** (or both) attributes.\n\n### Attribute Operators\n\nCurrently, only the `stringEquals` and the `stringMatch` operators are available. Resource attributes might support one or both operators.\nFor more information, see [Assigning access by using wildcard policies](https://cloud.ibm.com/docs/account?topic=account-wildcard).\n\n### Attribute Validations\n\nPolicy 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.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a policy and must match the ETag value of the existing policy.\nThe Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.\n", "schema": { "type": "string" } } ], "x-codegen-request-body-name": "policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRequest" } } }, "description": "Updated policy content to be saved.", "required": true }, "responses": { "200": { "description": "Policy update successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of SERVICE_NAME in the account.", "subjects": [ { "attributes": [ { "name": "iam_id", "value": "IBMid-123453user" } ] } ], "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "resources": [ { "attributes": [ { "name": "accountId", "value": "ACCOUNT_ID", "operator": "stringEquals" }, { "name": "serviceName", "value": "SERVICE_NAME", "operator": "stringEquals" } ] } ], "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "400": { "description": "Policy input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "A policy's type cannot be updated. Create a new policy and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to update policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PUT \\\n", "'https://iam.cloud.ibm.com/v1/policies' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"type\": \"access\",\n", " \"description\": \"Viewer role for for all instances of SERVICE_NAME in the account.\",\n", " \"subjects\": [\n", " {\n", " \"attributes\": [\n", " {\n", " \"name\": \"iam_id\",\n", " \"value\": \"IBMid-123453user\"\n", " }\n", " ]\n", " }\n", " ],\n", " \"roles\":[\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Viewer\"\n", " }\n", " ],\n", " \"resources\":[\n", " {\n", " \"attributes\": [\n", " {\n", " \"name\": \"accountId\",\n", " \"value\": \"$ACCOUNT_ID\"\n", " },\n", " {\n", " \"name\": \"serviceName\",\n", " \"value\": \"$SERVICE_NAME\"\n", " }\n", " ]\n", " }\n", " ]\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "subjectAttribute := &iampolicymanagementv1.SubjectAttribute{\n", " Name: core.StringPtr(\"iam_id\"),\n", " Value: &exampleUserID,\n", "}\n", "policySubjects := &iampolicymanagementv1.PolicySubject{\n", " Attributes: []iampolicymanagementv1.SubjectAttribute{*subjectAttribute},\n", "}\n", "accountIDResourceAttribute := &iampolicymanagementv1.ResourceAttribute{\n", " Name: core.StringPtr(\"accountId\"),\n", " Value: core.StringPtr(exampleAccountID),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.ResourceAttribute{\n", " Name: core.StringPtr(\"serviceType\"),\n", " Value: core.StringPtr(\"service\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "policyResourceTag := &iampolicymanagementv1.ResourceTag{\n", " Name: core.StringPtr(\"project\"),\n", " Value: core.StringPtr(\"prototype\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "policyResources := &iampolicymanagementv1.PolicyResource{\n", " Attributes: []iampolicymanagementv1.ResourceAttribute{\n", " *accountIDResourceAttribute, *serviceNameResourceAttribute},\n", " Tags: []iampolicymanagementv1.ResourceTag{*policyResourceTag},\n", "}\n", "updatedPolicyRoles := &iampolicymanagementv1.PolicyRole{\n", " RoleID: core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Editor\"),\n", "}\n", "\n", "options := iamPolicyManagementService.NewReplacePolicyOptions(\n", " examplePolicyID,\n", " examplePolicyETag,\n", " \"access\",\n", " []iampolicymanagementv1.PolicySubject{*policySubjects},\n", " []iampolicymanagementv1.PolicyRole{*updatedPolicyRoles},\n", " []iampolicymanagementv1.PolicyResource{*policyResources},\n", ")\n", "\n", "policy, response, err := iamPolicyManagementService.ReplacePolicy(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "examplePolicyETag = response.GetHeaders().Get(\"ETag\")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "SubjectAttribute subjectAttribute = new SubjectAttribute.Builder()\n", " .name(\"iam_id\")\n", " .value(EXAMPLE_USER_ID)\n", " .build();\n", "\n", "PolicySubject policySubjects = new PolicySubject.Builder()\n", " .addAttributes(subjectAttribute)\n", " .build();\n", "\n", "ResourceAttribute accountIdResourceAttribute = new ResourceAttribute.Builder()\n", " .name(\"accountId\")\n", " .value(exampleAccountId)\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "ResourceAttribute serviceNameResourceAttribute = new ResourceAttribute.Builder()\n", " .name(\"serviceType\")\n", " .value(\"service\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "ResourceTag policyResourceTag = new ResourceTag.Builder()\n", " .name(\"project\")\n", " .value(\"prototype\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "PolicyResource policyResources = new PolicyResource.Builder()\n", " .addAttributes(accountIdResourceAttribute)\n", " .addAttributes(serviceNameResourceAttribute)\n", " .addTags(policyResourceTag)\n", " .build();\n", "\n", "PolicyRole updatedPolicyRole = new PolicyRole.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Editor\")\n", " .build();\n", "\n", "ReplacePolicyOptions options = new ReplacePolicyOptions.Builder()\n", " .type(\"access\")\n", " .policyId(examplePolicyId)\n", " .ifMatch(examplePolicyEtag)\n", " .subjects(new ArrayList(Arrays.asList(policySubjects)))\n", " .roles(new ArrayList(Arrays.asList(updatedPolicyRole)))\n", " .resources(new ArrayList(Arrays.asList(policyResources)))\n", " .build();\n", "\n", "Response response = service.replacePolicy(options).execute();\n", "Policy policy = response.getResult();\n", "\n", "examplePolicyEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(policy);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const policySubjects = [\n", " {\n", " attributes: [\n", " {\n", " name: 'iam_id',\n", " value: exampleUserId,\n", " },\n", " ],\n", " },\n", "];\n", "const accountIdResourceAttribute = {\n", " name: 'accountId',\n", " value: exampleAccountId,\n", " operator: 'stringEquals',\n", "};\n", "const serviceNameResourceAttribute = {\n", " name: 'serviceType',\n", " value: 'service',\n", " operator: 'stringEquals',\n", "};\n", "const policyResourceTag = {\n", " name: 'project',\n", " operator: 'stringEquals',\n", " value: 'prototype',\n", "};\n", "const policyResources = [\n", " {\n", " attributes: [accountIdResourceAttribute, serviceNameResourceAttribute],\n", " tags: [policyResourceTag],\n", " },\n", "];\n", "const updatedPolicyRoles = [\n", " {\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Editor',\n", " },\n", "];\n", "const params = {\n", " type: 'access',\n", " policyId: examplePolicyId,\n", " ifMatch: examplePolicyETag,\n", " subjects: policySubjects,\n", " roles: updatedPolicyRoles,\n", " resources: policyResources,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.replacePolicy(params);\n", " examplePolicyETag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy_subjects = PolicySubject(attributes=[SubjectAttribute(name='iam_id', value=example_user_id)])\n", "account_id_resource_attribute = ResourceAttribute(name='accountId', value=example_account_id)\n", "service_name_resource_attribute = ResourceAttribute(name='serviceType', value='service')\n", "policy_resource_tag = ResourceTag(name='project', value='prototype')\n", "policy_resources = PolicyResource(\n", " attributes=[account_id_resource_attribute, service_name_resource_attribute], tags=[policy_resource_tag]\n", ")\n", "updated_policy_roles = PolicyRole(role_id='crn:v1:bluemix:public:iam::::role:Editor')\n", "\n", "response = iam_policy_management_service.replace_policy(\n", " type='access',\n", " policy_id=example_policy_id,\n", " if_match=example_policy_etag,\n", " subjects=[policy_subjects],\n", " roles=[updated_policy_roles],\n", " resources=[policy_resources],\n", ")\n", "policy = response.get_result()\n", "global example_updated_policy_etag\n", "example_updated_policy_etag = response.get_headers().get(\"Etag\")\n", "\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } }, "get": { "tags": [ "Policies" ], "summary": "Retrieve a policy by ID", "operationId": "get_policy", "description": "Retrieve a policy by providing a policy ID.", "responses": { "200": { "description": "Policy retrieval successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the policy.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateMetaData" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of SERVICE_NAME in the account.", "subjects": [ { "attributes": [ { "name": "iam_id", "value": "IBMid-123453user" } ] } ], "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "resources": [ { "attributes": [ { "name": "accountId", "value": "ACCOUNT_ID", "operator": "stringEquals" }, { "name": "serviceName", "value": "SERVICE_NAME", "operator": "stringEquals" } ] } ], "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policies/$POLICY_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewGetPolicyOptions(\n", " examplePolicyID,\n", ")\n", "\n", "policy, response, err := iamPolicyManagementService.GetPolicy(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "examplePolicyETag = response.GetHeaders().Get(\"ETag\")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetPolicyOptions options = new GetPolicyOptions.Builder()\n", " .policyId(examplePolicyId)\n", " .build();\n", "\n", "Response response = service.getPolicy(options).execute();\n", "PolicyTemplateMetaData policy = response.getResult();\n", "\n", "examplePolicyEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(policy);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyId: examplePolicyId,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.getPolicy(params);\n", " examplePolicyETag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.get_policy(policy_id=example_policy_id)\n", "policy = response.get_result()\n", "global example_policy_etag\n", "example_policy_etag = response.get_headers().get(\"Etag\")\n", "\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } }, "delete": { "tags": [ "Policies" ], "summary": "Delete a policy by ID", "operationId": "delete_policy", "description": "Delete a policy by providing a policy ID. A policy cannot be deleted if the subject ID\ncontains a locked service ID.\nIf the subject of the policy is a locked service-id, the request will fail.\n", "responses": { "204": { "description": "Policy deletion successful." }, "400": { "description": "Policy was not valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a locked service id, cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/policies/$POLICY_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewDeletePolicyOptions(\n", " examplePolicyID,\n", ")\n", "\n", "response, err := iamPolicyManagementService.DeletePolicy(options)\n", "if err != nil {\n", " panic(err)\n", "}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "DeletePolicyOptions options = new DeletePolicyOptions.Builder()\n", " .policyId(examplePolicyId)\n", " .build();\n", "\n", "Response response = service.deletePolicy(options).execute();" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyId: examplePolicyId,\n", "};\n", "\n", "try {\n", " await iamPolicyManagementService.deletePolicy(params);\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.delete_policy(policy_id=example_policy_id).get_result()\n", "\n", "print(json.dumps(response, indent=2))" ] } ] } ] } } }, "patch": { "tags": [ "Policies" ], "summary": "Restore a deleted policy by ID", "operationId": "update_policy_state", "description": "Restore a policy that has recently been deleted.\nA policy administrator might want to restore a deleted policy.\nTo restore a policy, use **`\"state\": \"active\"`** in the body.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a policy and must match the ETag value of the existing policy.\nThe Etag can be retrieved using the GET /v1/policies/{policy_id} API and looking at the ETag response header.\n", "schema": { "type": "string" } } ], "x-codegen-request-body-name": "policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchPolicyRequest" } } }, "description": "Policy attribute to be updated.", "required": true }, "responses": { "200": { "description": "Policy successfully restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of SERVICE_NAME in the account.", "subjects": [ { "attributes": [ { "name": "iam_id", "value": "IBMid-123453user" } ] } ], "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "resources": [ { "attributes": [ { "name": "accountId", "value": "ACCOUNT_ID", "operator": "stringEquals" }, { "name": "serviceName", "value": "SERVICE_NAME", "operator": "stringEquals" } ] } ], "href": "https://iam.cloud.ibm.com/v1/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "400": { "description": "Policy input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check missing parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PATCH \\\n", "'https://iam.cloud.ibm.com/v1/policies' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"state\": \"active\",\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewUpdatePolicyStateOptions(\n", " examplePolicyID,\n", " examplePolicyETag,\n", ")\n", "\n", "options.SetState(\"active\")\n", "\n", "policy, response, err := iamPolicyManagementService.UpdatePolicyState(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "UpdatePolicyStateOptions updatePolicyStateOptions = new UpdatePolicyStateOptions.Builder()\n", " .policyId(examplePolicyId)\n", " .ifMatch(examplePolicyEtag)\n", " .state(\"active\")\n", " .build();\n", "\n", "Response response = service.updatePolicyState(updatePolicyStateOptions).execute();\n", "Policy policy = response.getResult();\n", "\n", "System.out.println(policy);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyId: examplePolicyId,\n", " ifMatch: examplePolicyETag,\n", " state: 'active'\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.updatePolicyState(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy = iam_policy_management_service.update_policy_state(\n", " policy_id=example_policy_id, if_match=example_updated_policy_etag, state='active'\n", ").get_result()\n", "\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } } }, "/v2/policies": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "v2/Policies" ], "summary": "Get policies by attributes", "operationId": "list_v2_policies", "description": "Get policies and filter by attributes.\nWhile managing policies, you might want to retrieve\npolicies in the account and filter by attribute values.\nThis can be done through query parameters.\nThe following attributes are supported:\naccount_id, iam_id, access_group_id, type, service_type, sort, format and state.\naccount_id is a required query parameter.\nOnly policies that have the specified attributes and that\nthe caller has read access to are returned.\nIf the caller does not have read access to any policies an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID in which the policies belong to.", "schema": { "type": "string", "minLength": 1 } }, { "name": "iam_id", "in": "query", "description": "Optional IAM ID used to identify the subject.", "schema": { "type": "string", "minLength": 1 } }, { "name": "access_group_id", "in": "query", "description": "Optional access group id.", "schema": { "type": "string", "minLength": 1 } }, { "name": "type", "in": "query", "description": "Optional type of policy.", "schema": { "type": "string", "enum": [ "access", "authorization" ] } }, { "name": "service_type", "in": "query", "description": "Optional type of service.", "schema": { "type": "string", "enum": [ "service", "platform_service" ] } }, { "name": "service_name", "in": "query", "description": "Optional name of service.", "schema": { "type": "string", "minLength": 1 } }, { "name": "service_group_id", "in": "query", "description": "Optional ID of service group.", "schema": { "type": "string", "minLength": 1 } }, { "name": "sort", "in": "query", "description": "Optional top level policy field to sort results. Ascending sort is default. Descending sort available by prepending '-' to field, for example, '-last_modified_at'.\nNote that last permit information is only included when 'format=include_last_permit', for example, \"format=include_last_permit&sort=last_permit_at\"\nExample fields that can be sorted on:\n - 'type'\n - 'href'\n - 'created_at'\n - 'created_by_id'\n - 'last_modified_at'\n - 'last_modified_by_id'\n - 'state'\n - 'last_permit_at'\n - 'last_permit_frequency'", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Include additional data per policy returned\n* `include_last_permit` - returns details of when the policy last granted a permit decision and the number of times it has done so\n* `display` - returns the list of all actions included in each of the policy roles and translations for all relevant fields", "schema": { "type": "string", "enum": [ "include_last_permit", "display" ] } }, { "name": "state", "in": "query", "description": "The state of the policy.\n* `active` - returns active policies\n* `deleted` - returns non-active policies", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Policies retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PolicyCollection" }, "examples": { "response": { "value": { "policies": [ { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "subject": { "attributes": [ { "key": "iam_id", "operator": "stringEquals", "value": "IBMid-123453user" } ] }, "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ] } }, "resource": { "attributes": [ { "key": "accountId", "operator": "stringEquals", "value": "100abcde100a41abc100aza678abc0zz" }, { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours", "href": "https://iam.cloud.ibm.com/v2/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam.policy.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v2/policies?account_id=$ACCOUNT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewListV2PoliciesOptions(\n", " exampleAccountID,\n", ")\n", "options.SetIamID(exampleUserID)\n", "options.SetFormat(\"include_last_permit\")\n", "options.SetSort(\"-id\")\n", "\n", "policyList, response, err := iamPolicyManagementService.ListV2Policies(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyList, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListV2PoliciesOptions options = new ListV2PoliciesOptions.Builder()\n", " .accountId(exampleAccountId)\n", " .iamId(EXAMPLE_USER_ID)\n", " .format(\"include_last_permit\")\n", " .build();\n", "\n", "Response response = service.listV2Policies(options).execute();\n", "V2PolicyCollection policyCollection = response.getResult();\n", "\n", "System.out.println(policyCollection);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " accountId: exampleAccountId,\n", " iamId: exampleUserId,\n", " format: 'include_last_permit',\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.listV2Policies(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy_list = iam_policy_management_service.list_v2_policies(\n", " account_id=example_account_id, iam_id=example_user_id, format='include_last_permit'\n", ").get_result()\n", "\n", "print(json.dumps(policy_list, indent=2))" ] } ] } ] } } }, "post": { "tags": [ "v2/Policies" ], "summary": "Create a policy", "operationId": "create_v2_policy", "description": "Creates a policy to grant access between a subject and a resource.\nCurrently, there is one type of a v2/policy: **access**.\nA policy administrator might want to create an access policy\nthat grants access to a user, service-id, or an access group.\n\n### Access\n\nTo create an access policy, use **`\"type\": \"access\"`** in the body.\nThe supported subject attributes are **`iam_id`** and **`access_group_id`**.\nUse the **`iam_id`** subject attribute to assign access to a user or service-id.\nUse the **`access_group_id`** subject attribute to assign access to an access group.\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nThe policy resource must include either the **`serviceType`**, **`serviceName`**, **`resourceGroupId`** or **`service_group_id`** attribute and the **`accountId`** attribute.\nIn 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`**.\nThe possible combination operators are **`and`** and **`or`**.\n\nCurrently, we support two types of patterns:\n\n1. `time-based`: Used to specify a time-based restriction\n\nCombine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week).\nFor example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule:\n```json\n \"rule\": {\n \"operator\": \"and\",\n \"conditions\": [{\n \"key\": \"{{environment.attributes.day_of_week}}\",\n \"operator\": \"dayOfWeekAnyOf\",\n \"value\": [\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"]\n },\n \"key\": \"{{environment.attributes.current_time}}\",\n \"operator\": \"timeGreaterThanOrEquals\",\n \"value\": \"09:00:00+00:00\"\n },\n \"key\": \"{{environment.attributes.current_time}}\",\n \"operator\": \"timeLessThanOrEquals\",\n \"value\": \"17:00:00+00:00\"\n }]\n }\n```\nYou can use the following operators in the **`key`** and **`value`** pair:\n```\n 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals',\n 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals',\n 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals',\n 'dayOfWeekEquals', 'dayOfWeekAnyOf'\n```\n\nThe 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\"`**.\nFor more information, see [Time-based conditions operators](/docs/account?topic=account-iam-condition-properties&interface=ui#policy-condition-properties) and\n[Limiting access with time-based conditions](/docs/account?topic=account-iam-time-based&interface=ui).\nIf the subject is a locked service-id, the request will fail.\n\n2. `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.\n\nCombine conditions to specify an attribute-based condition using AND/OR-based operators.\n\nFor example, a policy can grant access based on multiple conditions applied on the resource attributes below:\n```json\n \"pattern\": \"attribute-based-condition:resource:literal-and-wildcard\"\n \"rule\": {\n \"operator\": \"or\",\n \"conditions\": [\n {\n \"operator\": \"and\",\n \"conditions\": [\n {\n \"key\": \"{{resource.attributes.prefix}}\",\n \"operator\": \"stringEquals\",\n \"value\": \"home/test\"\n },\n {\n \"key\": \"{{environment.attributes.delimiter}}\",\n \"operator\": \"stringEquals\",\n \"value\": \"/\"\n }\n ]\n },\n {\n \"key\": \"{{resource.attributes.path}}\",\n \"operator\": \"stringMatch\",\n \"value\": \"home/David/*\"\n }\n ]\n }\n```\n\nIn addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` **OR** \nthe `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, \nmaking 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](/docs/account?topic=account-wildcard#string-comparisons).\n\n### Authorization\n\nAuthorization policies are supported by services on a case by case basis.\nRefer to service documentation to verify their support of authorization policies.\nTo create an authorization policy, use **`\"type\": \"authorization\"`** in the body.\nThe subject attributes must match the supported authorization subjects of the resource.\nMultiple subject attributes might be provided. The following attributes are supported:\n serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nThe user must also have the same level of access or greater to the target resource in order to grant the role.\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nBoth the policy subject and the policy resource must include the **`accountId`** attributes. The policy subject must include either **`serviceName`** or **`resourceGroupId`** (or both) attributes.\n\n### Attribute Operators\n\nCurrently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available.\nFor more information, see [Assigning access by using wildcard policies](https://cloud.ibm.com/docs/account?topic=account-wildcard).\n\n### Attribute Validations\n\nPolicy 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.\n", "x-codegen-request-body-name": "v2_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUpdateV2PolicyRequest" } } }, "description": "A policy to be created.", "required": true }, "responses": { "201": { "description": "Policy creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Policy" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "subject": { "attributes": [ { "key": "iam_id", "operator": "stringEquals", "value": "IBMid-123453user" } ] }, "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ] } }, "resource": { "attributes": [ { "key": "accountId", "operator": "stringEquals", "value": "100abcde100a41abc100aza678abc0zz" }, { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours", "href": "https://iam.cloud.ibm.com/v2/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Policy input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to create policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum policies quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum policies quota (4020) for account 100abcde100a41abc100aza678abc0zz." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam.policy.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v2/policies' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"type\": \"access\",\n", " \"description\": \"Editor role for SERVICE_NAME\\'s RESOURCE_NAME\",\n", " \"subject\": {\n", " \"attributes\": [\n", " {\n", " \"key\": \"iam_id\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"IBMid-123453user\"\n", " }\n", " ]\n", " },\n", " \"control\": {\n", " \"grant\": {\n", " \"roles\": [\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Editor\"\n", " }\n", " ]\n", " }\n", " },\n", " \"resource\": {\n", " \"attributes\": [\n", " {\n", " \"key\": \"accountId\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$ACCOUNT_ID\"\n", " },\n", " {\n", " \"key\": \"serviceName\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$SERVICE_NAME\"\n", " },\n", " {\n", " \"key\": \"resource\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$RESOURCE_NAME\"\n", " }\n", " ]\n", " },\n", " \"rule\" :{\n", " \"key\": \"{{environment.attributes.day_of_week}}\",\n", " \"operator\": \"dayOfWeekAnyOf\",\n", " \"value\": [\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"]\n", " },\n", " \"pattern\": \"time-based-conditions:weekly:all-day\"\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "subjectAttribute := &iampolicymanagementv1.V2PolicySubjectAttribute{\n", " Key: core.StringPtr(\"iam_id\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: &exampleUserID,\n", "}\n", "policySubject := &iampolicymanagementv1.V2PolicySubject{\n", " Attributes: []iampolicymanagementv1.V2PolicySubjectAttribute{*subjectAttribute},\n", "}\n", "policyRole := &iampolicymanagementv1.Roles{\n", " RoleID: core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Viewer\"),\n", "}\n", "v2PolicyGrant := &iampolicymanagementv1.Grant{\n", " Roles: []iampolicymanagementv1.Roles{*policyRole},\n", "}\n", "v2PolicyControl := &iampolicymanagementv1.Control{\n", " Grant: v2PolicyGrant,\n", "}\n", "accountIDResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"accountId\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(exampleAccountID),\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"serviceType\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(\"service\"),\n", "}\n", "policyResourceTag := &iampolicymanagementv1.V2PolicyResourceTag{\n", " Key: core.StringPtr(\"project\"),\n", " Value: core.StringPtr(\"prototype\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", "}\n", "policyResource := &iampolicymanagementv1.V2PolicyResource{\n", " Attributes: []iampolicymanagementv1.V2PolicyResourceAttribute{\n", " *accountIDResourceAttribute, *serviceNameResourceAttribute},\n", " Tags: []iampolicymanagementv1.V2PolicyResourceTag{*policyResourceTag},\n", "}\n", "weeklyConditionAttribute := &iampolicymanagementv1.NestedCondition{\n", " Key: core.StringPtr(\"{{environment.attributes.day_of_week}}\"),\n", " Operator: core.StringPtr(\"dayOfWeekAnyOf\"),\n", " Value: []string{\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"},\n", "}\n", "startConditionAttribute := &iampolicymanagementv1.NestedCondition{\n", " Key: core.StringPtr(\"{{environment.attributes.current_time}}\"),\n", " Operator: core.StringPtr(\"timeGreaterThanOrEquals\"),\n", " Value: core.StringPtr(\"09:00:00+00:00\"),\n", "}\n", "endConditionAttribute := &iampolicymanagementv1.NestedCondition{\n", " Key: core.StringPtr(\"{{environment.attributes.current_time}}\"),\n", " Operator: core.StringPtr(\"timeLessThanOrEquals\"),\n", " Value: core.StringPtr(\"17:00:00+00:00\"),\n", "}\n", "policyRule := &iampolicymanagementv1.V2PolicyRule{\n", " Operator: core.StringPtr(\"and\"),\n", " Conditions: []iampolicymanagementv1.NestedConditionIntf{\n", " weeklyConditionAttribute, startConditionAttribute, endConditionAttribute},\n", "}\n", "\n", "options := iamPolicyManagementService.NewCreateV2PolicyOptions(\n", " v2PolicyControl,\n", " \"access\",\n", ")\n", "options.SetSubject(policySubject)\n", "options.SetResource(policyResource)\n", "options.SetRule(policyRule)\n", "options.SetPattern(*core.StringPtr(\"time-based-conditions:weekly:custom-hours\"))\n", "\n", "policy, response, err := iamPolicyManagementService.CreateV2Policy(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "examplePolicyID = *policy.ID\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "V2PolicySubjectAttribute subjectAttribute = new V2PolicySubjectAttribute.Builder()\n", " .key(\"iam_id\")\n", " .value(EXAMPLE_USER_ID)\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicySubject policySubject = new V2PolicySubject.Builder()\n", " .addAttributes(subjectAttribute)\n", " .build();\n", "\n", "V2PolicyResourceAttribute accountIdResourceAttribute = new V2PolicyResourceAttribute.Builder()\n", " .key(\"accountId\")\n", " .value(exampleAccountId)\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicyResourceAttribute serviceNameResourceAttribute = new V2PolicyResourceAttribute.Builder()\n", " .key(\"serviceType\")\n", " .value(\"service\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicyResourceTag policyResourceTag = new V2PolicyResourceTag.Builder()\n", " .key(\"project\")\n", " .value(\"prototype\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicyResource policyResource = new V2PolicyResource.Builder()\n", " .addAttributes(accountIdResourceAttribute)\n", " .addAttributes(serviceNameResourceAttribute)\n", " .addTags(policyResourceTag)\n", " .build();\n", "\n", "Roles policyRoles = new Roles.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Viewer\")\n", " .build();\n", "\n", "Grant policyGrant = new Grant.Builder()\n", " .roles(Arrays.asList(policyRoles))\n", " .build();\n", "\n", "Control control = new Control.Builder()\n", " .grant(policyGrant)\n", " .build();\n", "\n", "NestedConditionRuleAttribute weeklyConditionAttribute = new NestedConditionRuleAttribute.Builder()\n", " .key(\"{{environment.attributes.day_of_week}}\")\n", " .value(new ArrayList(Arrays.asList(\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\")))\n", " .operator(\"dayOfWeekAnyOf\")\n", " .build();\n", "\n", "NestedConditionRuleAttribute startConditionAttribute = new NestedConditionRuleAttribute.Builder()\n", " .key(\"{{environment.attributes.current_time}}\")\n", " .value(\"09:00:00+00:00\")\n", " .operator(\"timeGreaterThanOrEquals\")\n", " .build();\n", "\n", "NestedConditionRuleAttribute endConditionAttribute = new NestedConditionRuleAttribute.Builder()\n", " .key(\"{{environment.attributes.current_time}}\")\n", " .value(\"17:00:00+00:00\")\n", " .operator(\"timeLessThanOrEquals\")\n", " .build();\n", "\n", "V2PolicyRuleRuleWithNestedConditions policyRule = new V2PolicyRuleRuleWithNestedConditions.Builder()\n", " .operator(\"and\")\n", " .conditions(new ArrayList(Arrays.asList(weeklyConditionAttribute, startConditionAttribute, endConditionAttribute)))\n", " .build();\n", "\n", "CreateV2PolicyOptions options = new CreateV2PolicyOptions.Builder()\n", " .type(\"access\")\n", " .subject(policySubject)\n", " .control(control)\n", " .resource(policyResource)\n", " .rule(policyRule)\n", " .pattern(\"time-based-conditions:weekly:custom-hours\")\n", " .build();\n", "\n", "Response response = service.createV2Policy(options).execute();\n", "V2Policy policy = response.getResult();\n", "\n", "exampleV2PolicyId = policy.getId();\n", "\n", "System.out.println(policy);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const policySubject = {\n", " attributes: [\n", " {\n", " key: 'iam_id',\n", " operator: 'stringEquals',\n", " value: exampleUserId,\n", " },\n", " ],\n", "};\n", "const policyResourceAccountAttribute = {\n", " key: 'accountId',\n", " value: exampleAccountId,\n", " operator: 'stringEquals',\n", "};\n", "const policyResourceServiceAttribute = {\n", " key: 'serviceType',\n", " operator: 'stringEquals',\n", " value: 'service',\n", "};\n", "const policyResource = {\n", " attributes: [policyResourceAccountAttribute, policyResourceServiceAttribute]\n", "};\n", "const policyControl = {\n", " grant: {\n", " roles: [{\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Viewer',\n", " }],\n", " }\n", "};\n", "const policyRule = {\n", " operator: 'and',\n", " conditions: [\n", " {\n", " key: '{{environment.attributes.day_of_week}}',\n", " operator: 'dayOfWeekAnyOf',\n", " value: ['1+00:00', '2+00:00', '3+00:00', '4+00:00', '5+00:00'],\n", " },\n", " {\n", " key: '{{environment.attributes.current_time}}',\n", " operator: 'timeGreaterThanOrEquals',\n", " value: '09:00:00+00:00',\n", " },\n", " {\n", " key: '{{environment.attributes.current_time}}',\n", " operator: 'timeLessThanOrEquals',\n", " value: '17:00:00+00:00',\n", " },\n", " ],\n", "}\n", "const policyPattern = 'time-based-conditions:weekly:custom-hours'\n", "const params = {\n", " type: 'access',\n", " subject: policySubject,\n", " control: policyControl,\n", " resource: policyResource,\n", " rule: policyRule,\n", " pattern: policyPattern,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.createV2Policy(params);\n", " examplePolicyId = res.result.id;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy_subject = V2PolicySubject(\n", " attributes=[V2PolicySubjectAttribute(key='iam_id', value=example_user_id, operator='stringEquals')]\n", ")\n", "policy_role = PolicyRole(role_id='crn:v1:bluemix:public:iam::::role:Viewer')\n", "account_id_resource_attribute = V2PolicyResourceAttribute(\n", " key='accountId', value=example_account_id, operator='stringEquals'\n", ")\n", "service_name_resource_attribute = V2PolicyResourceAttribute(\n", " key='serviceType', value='service', operator='stringEquals'\n", ")\n", "policy_resource_tag = V2PolicyResourceTag(key='project', value='prototype', operator='stringEquals')\n", "policy_resource = V2PolicyResource(\n", " attributes=[account_id_resource_attribute, service_name_resource_attribute], tags=[policy_resource_tag]\n", ")\n", "policy_control = Control(grant=Grant(roles=[policy_role]))\n", "policy_rule = V2PolicyRuleRuleWithNestedConditions(\n", " operator='and',\n", " conditions=[\n", " RuleAttribute(\n", " key='{{environment.attributes.day_of_week}}',\n", " operator='dayOfWeekAnyOf',\n", " value=['1+00:00', '2+00:00', '3+00:00', '4+00:00', '5+00:00'],\n", " ),\n", " RuleAttribute(\n", " key='{{environment.attributes.current_time}}',\n", " operator='timeGreaterThanOrEquals',\n", " value='09:00:00+00:00',\n", " ),\n", " RuleAttribute(\n", " key='{{environment.attributes.current_time}}',\n", " operator='timeLessThanOrEquals',\n", " value='17:00:00+00:00',\n", " ),\n", " ],\n", ")\n", "policy_pattern = 'time-based-conditions:weekly:custom-hours'\n", "\n", "policy = iam_policy_management_service.create_v2_policy(\n", " type='access',\n", " subject=policy_subject,\n", " control=policy_control,\n", " resource=policy_resource,\n", " rule=policy_rule,\n", " pattern=policy_pattern,\n", ").get_result()\n", "\n", "global example_policy_id\n", "example_policy_id = policy['id']\n", "\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } } }, "/v2/policies/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy ID.", "schema": { "type": "string", "minLength": 1 } } ], "put": { "tags": [ "v2/Policies" ], "summary": "Update a policy", "operationId": "replace_v2_policy", "description": "Update a policy to grant access between a subject and a resource.\nA policy administrator might want to update an existing policy.\n\n### Access\n\nTo update an access policy, use **`\"type\": \"access\"`** in the body.\nThe supported subject attributes are **`iam_id`** and **`access_group_id`**.\nUse the **`iam_id`** subject attribute to assign access to a user or service-id.\nUse the **`access_group_id`** subject attribute to assign access to an access group.\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nThe policy resource must include either the **`serviceType`**, **`serviceName`**, **`resourceGroupId`** or **`service_group_id`** attribute and the **`accountId`** attribute.\nIn 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`**.\nThe possible combination operators are **`and`** and **`or`**.\n\nCurrently, we support two types of patterns:\n\n1. `time-based`: Used to specify a time-based restriction\n\nCombine conditions to specify a time-based restriction (e.g., access only during business hours, during the Monday-Friday work week).\nFor example, a policy can grant access Monday-Friday, 9:00am-5:00pm using the following rule:\n```json\n \"rule\": {\n \"operator\": \"and\",\n \"conditions\": [{\n \"key\": \"{{environment.attributes.day_of_week}}\",\n \"operator\": \"dayOfWeekAnyOf\",\n \"value\": [\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"]\n },\n \"key\": \"{{environment.attributes.current_time}}\",\n \"operator\": \"timeGreaterThanOrEquals\",\n \"value\": \"09:00:00+00:00\"\n },\n \"key\": \"{{environment.attributes.current_time}}\",\n \"operator\": \"timeLessThanOrEquals\",\n \"value\": \"17:00:00+00:00\"\n }]\n }\n```\nYou can use the following operators in the **`key`** and **`value`** pair:\n```\n 'timeLessThan', 'timeLessThanOrEquals', 'timeGreaterThan', 'timeGreaterThanOrEquals',\n 'dateLessThan', 'dateLessThanOrEquals', 'dateGreaterThan', 'dateGreaterThanOrEquals',\n 'dateTimeLessThan', 'dateTimeLessThanOrEquals', 'dateTimeGreaterThan', 'dateTimeGreaterThanOrEquals',\n 'dayOfWeekEquals', 'dayOfWeekAnyOf'\n```\nThe 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\"`**.\nFor more information, see [Time-based conditions operators](/docs/account?topic=account-iam-condition-properties&interface=ui#policy-condition-properties) and\n[Limiting access with time-based conditions](/docs/account?topic=account-iam-time-based&interface=ui).\nIf the subject is a locked service-id, the request will fail.\n\n2. `attribute-based`: Used to specify a combination of OR/AND based conditions applied on resource attributes.\n\nCombine conditions to specify an attribute-based condition using AND/OR-based operators.\n\nFor example, a policy can grant access based on multiple conditions applied on the resource attributes below:\n```json\n \"pattern\": \"attribute-based-condition:resource:literal-and-wildcard\"\n \"rule\": {\n \"operator\": \"or\",\n \"conditions\": [\n {\n \"operator\": \"and\",\n \"conditions\": [\n {\n \"key\": \"{{resource.attributes.prefix}}\",\n \"operator\": \"stringEquals\",\n \"value\": \"home/test\"\n },\n {\n \"key\": \"{{environment.attributes.delimiter}}\",\n \"operator\": \"stringEquals\",\n \"value\": \"/\"\n }\n ]\n },\n {\n \"key\": \"{{resource.attributes.path}}\",\n \"operator\": \"stringMatch\",\n \"value\": \"home/David/*\"\n }\n ]\n }\n```\n\nIn addition to satisfying the `resources` section, the policy grants permission only if either the `path` begins with `home/David/` **OR** \nthe `prefix` is `home/test` and the `delimiter` is `/`. This mechanism helps you consolidate multiple policies in to a single policy, \nmaking 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](/docs/account?topic=account-wildcard#string-comparisons).\n\n### Authorization\n\nTo update an authorization policy, use **`\"type\": \"authorization\"`** in the body.\nThe subject attributes must match the supported authorization subjects of the resource.\nMultiple subject attributes might be provided. The following attributes are supported:\n serviceName, serviceInstance, region, resourceType, resource, accountId, resourceGroupId\nAssign roles that are supported by the service or platform roles. For more information, see [IAM roles and actions](/docs/account?topic=account-iam-service-roles-actions).\nThe user must also have the same level of access or greater to the target resource in order to grant the role.\nUse only the resource attributes supported by the service. To view a service's or the platform's supported attributes, check the [documentation](/docs?tab=all-docs).\nBoth the policy subject and the policy resource must include the **`accountId`** attributes. The policy subject must include either **`serviceName`** or **`resourceGroupId`** (or both) attributes.\n\n### Attribute Operators\n\nCurrently, only the `stringEquals`, `stringMatch`, and `stringEquals` operators are available.\nFor more information, see [Assigning access by using wildcard policies](https://cloud.ibm.com/docs/account?topic=account-wildcard).\n\n### Attribute Validations\n\nPolicy 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.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a policy and must match the ETag value of the existing policy.\nThe Etag can be retrieved using the GET /v2/policies/{id} API and looking at the ETag response header.\n", "schema": { "type": "string", "minLength": 1 } } ], "x-codegen-request-body-name": "v2_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUpdateV2PolicyRequest" } } }, "description": "Updated policy content to be saved.", "required": true }, "responses": { "200": { "description": "Policy update successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Policy" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours, except Friday.", "subject": { "attributes": [ { "key": "iam_id", "operator": "stringEquals", "value": "IBMid-123453user" } ] }, "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ] } }, "resource": { "attributes": [ { "key": "accountId", "operator": "stringEquals", "value": "100abcde100a41abc100aza678abc0zz" }, { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours", "href": "https://iam.cloud.ibm.com/v2/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Policy input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "A policy's type cannot be updated. Create a new policy and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy already exists for the given subject and resource. You can update that policy or delete it and create a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_conflict_error", "message": "Failed to update policy.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy": "POLICY" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam.policy.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PUT \\\n", "'https://iam.cloud.ibm.com/v2/policies' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"type\": \"access\",\n", " \"description\": \"Viewer role for for all instances of SERVICE_NAME in the account.\",\n", " \"subject\": {\n", " \"attributes\": [\n", " {\n", " \"key\": \"iam_id\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"IBMid-123453user\"\n", " }\n", " ]\n", " },\n", " \"control\": {\n", " \"grant\": {\n", " \"roles\": [\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Viewer\"\n", " }\n", " ]\n", " }\n", " },\n", " \"resource\": {\n", " \"attributes\": [\n", " {\n", " \"key\": \"accountId\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$ACCOUNT_ID\"\n", " },\n", " {\n", " \"key\": \"serviceName\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$SERVICE_NAME\"\n", " }\n", " ]\n", " },\n", " \"rule\": {\n", " \"key\": \"{{environment.attributes.day_of_week}}\",\n", " \"operator\": \"dayOfWeekAnyOf\",\n", " \"value\": [\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"]\n", " },\n", " \"pattern\": \"time-based-conditions:weekly:all-day\"\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "subjectAttribute := &iampolicymanagementv1.V2PolicySubjectAttribute{\n", " Key: core.StringPtr(\"iam_id\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: &exampleUserID,\n", "}\n", "policySubject := &iampolicymanagementv1.V2PolicySubject{\n", " Attributes: []iampolicymanagementv1.V2PolicySubjectAttribute{*subjectAttribute},\n", "}\n", "updatedPolicyRole := &iampolicymanagementv1.Roles{\n", " RoleID: core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Editor\"),\n", "}\n", "v2PolicyGrant := &iampolicymanagementv1.Grant{\n", " Roles: []iampolicymanagementv1.Roles{*updatedPolicyRole},\n", "}\n", "v2PolicyControl := &iampolicymanagementv1.Control{\n", " Grant: v2PolicyGrant,\n", "}\n", "accountIDResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"accountId\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(exampleAccountID),\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"serviceType\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(\"service\"),\n", "}\n", "policyResource := &iampolicymanagementv1.V2PolicyResource{\n", " Attributes: []iampolicymanagementv1.V2PolicyResourceAttribute{\n", " *accountIDResourceAttribute, *serviceNameResourceAttribute},\n", "}\n", "\n", "options := iamPolicyManagementService.NewReplaceV2PolicyOptions(\n", " examplePolicyID,\n", " examplePolicyETag,\n", " v2PolicyControl,\n", " \"access\",\n", ")\n", "weeklyConditionAttribute := &iampolicymanagementv1.NestedCondition{\n", " Key: core.StringPtr(\"{{environment.attributes.day_of_week}}\"),\n", " Operator: core.StringPtr(\"dayOfWeekAnyOf\"),\n", " Value: []string{\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\"},\n", "}\n", "startConditionAttribute := &iampolicymanagementv1.NestedCondition{\n", " Key: core.StringPtr(\"{{environment.attributes.current_time}}\"),\n", " Operator: core.StringPtr(\"timeGreaterThanOrEquals\"),\n", " Value: core.StringPtr(\"09:00:00+00:00\"),\n", "}\n", "endConditionAttribute := &iampolicymanagementv1.NestedCondition{\n", " Key: core.StringPtr(\"{{environment.attributes.current_time}}\"),\n", " Operator: core.StringPtr(\"timeLessThanOrEquals\"),\n", " Value: core.StringPtr(\"17:00:00+00:00\"),\n", "}\n", "policyRule := &iampolicymanagementv1.V2PolicyRule{\n", " Operator: core.StringPtr(\"and\"),\n", " Conditions: []iampolicymanagementv1.NestedConditionIntf{\n", " weeklyConditionAttribute, startConditionAttribute, endConditionAttribute},\n", "}\n", "options.SetRule(policyRule)\n", "options.SetPattern(*core.StringPtr(\"time-based-conditions:weekly:custom-hours\"))\n", "options.SetSubject(policySubject)\n", "options.SetResource(policyResource)\n", "\n", "policy, response, err := iamPolicyManagementService.ReplaceV2Policy(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "V2PolicySubjectAttribute subjectAttribute = new V2PolicySubjectAttribute.Builder()\n", " .key(\"iam_id\")\n", " .value(EXAMPLE_USER_ID)\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicySubject policySubject = new V2PolicySubject.Builder()\n", " .addAttributes(subjectAttribute)\n", " .build();\n", "\n", "V2PolicyResourceAttribute accountIdResourceAttribute = new V2PolicyResourceAttribute.Builder()\n", " .key(\"accountId\")\n", " .value(exampleAccountId)\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicyResourceAttribute serviceNameResourceAttribute = new V2PolicyResourceAttribute.Builder()\n", " .key(\"serviceType\")\n", " .value(\"service\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicyResourceTag policyResourceTag = new V2PolicyResourceTag.Builder()\n", " .key(\"project\")\n", " .value(\"prototype\")\n", " .operator(\"stringEquals\")\n", " .build();\n", "\n", "V2PolicyResource policyResource = new V2PolicyResource.Builder()\n", " .addAttributes(accountIdResourceAttribute)\n", " .addAttributes(serviceNameResourceAttribute)\n", " .addTags(policyResourceTag)\n", " .build();\n", "\n", "Roles updatedPolicyRole = new Roles.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Editor\")\n", " .build();\n", "Grant policyGrant = new Grant.Builder()\n", " .roles(Arrays.asList(updatedPolicyRole))\n", " .build();\n", "\n", "Control policyControl = new Control.Builder()\n", " .grant(policyGrant)\n", " .build();\n", "\n", "NestedConditionRuleAttribute weeklyConditionAttribute = new NestedConditionRuleAttribute.Builder()\n", " .key(\"{{environment.attributes.day_of_week}}\")\n", " .value(new ArrayList(Arrays.asList(\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\")))\n", " .operator(\"dayOfWeekAnyOf\")\n", " .build();\n", "\n", "NestedConditionRuleAttribute startConditionAttribute = new NestedConditionRuleAttribute.Builder()\n", " .key(\"{{environment.attributes.current_time}}\")\n", " .value(\"09:00:00+00:00\")\n", " .operator(\"timeGreaterThanOrEquals\")\n", " .build();\n", "\n", "NestedConditionRuleAttribute endConditionAttribute = new NestedConditionRuleAttribute.Builder()\n", " .key(\"{{environment.attributes.current_time}}\")\n", " .value(\"17:00:00+00:00\")\n", " .operator(\"timeLessThanOrEquals\")\n", " .build();\n", "\n", "V2PolicyRuleRuleWithNestedConditions policyRule = new V2PolicyRuleRuleWithNestedConditions.Builder()\n", " .operator(\"and\")\n", " .conditions(new ArrayList(Arrays.asList(weeklyConditionAttribute, startConditionAttribute, endConditionAttribute)))\n", " .build();\n", "\n", "ReplaceV2PolicyOptions options = new ReplaceV2PolicyOptions.Builder()\n", " .type(\"access\")\n", " .id(exampleV2PolicyId)\n", " .ifMatch(exampleV2PolicyEtag)\n", " .subject(policySubject)\n", " .control(policyControl)\n", " .resource(policyResource)\n", " .rule(policyRule)\n", " .pattern(\"time-based-conditions:weekly:custom-hours\")\n", " .build();\n", "\n", "Response response = service.replaceV2Policy(options).execute();\n", "V2Policy policy = response.getResult();\n", "\n", "exampleV2PolicyEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(policy);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const policySubject = {\n", " attributes: [\n", " {\n", " key: 'iam_id',\n", " operator: 'stringEquals',\n", " value: exampleUserId,\n", " },\n", " ],\n", "};\n", "const policyResourceAccountAttribute = {\n", " key: 'accountId',\n", " value: exampleAccountId,\n", " operator: 'stringEquals',\n", "};\n", "const policyResourceServiceAttribute = {\n", " key: 'serviceType',\n", " operator: 'stringEquals',\n", " value: 'service',\n", "};\n", "const policyResource = {\n", " attributes: [policyResourceAccountAttribute, policyResourceServiceAttribute]\n", "};\n", "const updatedPolicyControl = {\n", " grant: {\n", " roles: [{\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Editor',\n", " }],\n", " }\n", "};\n", "const policyRule = {\n", " operator: 'and',\n", " conditions: [\n", " {\n", " key: '{{environment.attributes.day_of_week}}',\n", " operator: 'dayOfWeekAnyOf',\n", " value: ['1+00:00', '2+00:00', '3+00:00', '4+00:00', '5+00:00'],\n", " },\n", " {\n", " key: '{{environment.attributes.current_time}}',\n", " operator: 'timeGreaterThanOrEquals',\n", " value: '09:00:00+00:00',\n", " },\n", " {\n", " key: '{{environment.attributes.current_time}}',\n", " operator: 'timeLessThanOrEquals',\n", " value: '17:00:00+00:00',\n", " },\n", " ],\n", "}\n", "const policyPattern = 'time-based-conditions:weekly:custom-hours'\n", "const params = {\n", " type: 'access',\n", " id: examplePolicyId,\n", " ifMatch: examplePolicyETag,\n", " subject: policySubject,\n", " control: updatedPolicyControl,\n", " resource: policyResource,\n", " rule: policyRule,\n", " pattern: policyPattern,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.replaceV2Policy(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policy_subject = V2PolicySubject(\n", " attributes=[V2PolicySubjectAttribute(key='iam_id', value=example_user_id, operator='stringEquals')]\n", ")\n", "updated_policy_role = PolicyRole(role_id='crn:v1:bluemix:public:iam::::role:Editor')\n", "account_id_resource_attribute = V2PolicyResourceAttribute(\n", " key='accountId', value=example_account_id, operator='stringEquals'\n", ")\n", "service_name_resource_attribute = V2PolicyResourceAttribute(\n", " key='serviceType', value='service', operator='stringEquals'\n", ")\n", "policy_resource_tag = V2PolicyResourceTag(key='project', value='prototype', operator='stringEquals')\n", "policy_resource = PolicyResource(\n", " attributes=[account_id_resource_attribute, service_name_resource_attribute], tags=[policy_resource_tag]\n", ")\n", "policy_control = Control(grant=Grant(roles=[updated_policy_role]))\n", "policy_rule = V2PolicyRuleRuleWithNestedConditions(\n", " operator='and',\n", " conditions=[\n", " RuleAttribute(\n", " key='{{environment.attributes.day_of_week}}',\n", " operator='dayOfWeekAnyOf',\n", " value=['1+00:00', '2+00:00', '3+00:00', '4+00:00', '5+00:00'],\n", " ),\n", " RuleAttribute(\n", " key='{{environment.attributes.current_time}}',\n", " operator='timeGreaterThanOrEquals',\n", " value='09:00:00+00:00',\n", " ),\n", " RuleAttribute(\n", " key='{{environment.attributes.current_time}}',\n", " operator='timeLessThanOrEquals',\n", " value='17:00:00+00:00',\n", " ),\n", " ],\n", ")\n", "policy_pattern = 'time-based-conditions:weekly:custom-hours'\n", "\n", "response = iam_policy_management_service.replace_v2_policy(\n", " type='access',\n", " id=example_policy_id,\n", " if_match=example_policy_etag,\n", " subject=policy_subject,\n", " control=policy_control,\n", " resource=policy_resource,\n", " rule=policy_rule,\n", " pattern=policy_pattern,\n", ")\n", "policy = response.get_result()\n", "\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } }, "get": { "tags": [ "v2/Policies" ], "summary": "Retrieve a policy by ID", "operationId": "get_v2_policy", "description": "Retrieve a policy by providing a policy ID.", "parameters": [ { "name": "format", "in": "query", "description": "Include additional data for policy returned\n* `include_last_permit` - returns details of when the policy last granted a permit decision and the number of times it has done so\n* `display` - returns the list of all actions included in each of the policy roles and translations for all relevant fields", "schema": { "type": "string", "enum": [ "include_last_permit", "display" ] } } ], "responses": { "200": { "description": "Policy retrieval successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the policy.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PolicyTemplateMetaData" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "subject": { "attributes": [ { "key": "iam_id", "operator": "stringEquals", "value": "IBMid-123453user" } ] }, "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ] } }, "resource": { "attributes": [ { "key": "accountId", "operator": "stringEquals", "value": "100abcde100a41abc100aza678abc0zz" }, { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours", "href": "https://iam.cloud.ibm.com/v2/policies/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam.policy.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v2/policies/$POLICY_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewGetV2PolicyOptions(\n", " examplePolicyID,\n", ")\n", "\n", "policy, response, err := iamPolicyManagementService.GetV2Policy(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policy, \"\", \" \")\n", "examplePolicyETag = response.GetHeaders().Get(\"ETag\")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetV2PolicyOptions options = new GetV2PolicyOptions.Builder()\n", " .id(exampleV2PolicyId)\n", " .build();\n", "\n", "Response response = service.getV2Policy(options).execute();\n", "V2PolicyTemplateMetaData policy = response.getResult();\n", "\n", "exampleV2PolicyEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(policy);\n", "\n", "\n", "GetV2PolicyOptions options = new GetV2PolicyOptions.Builder()\n", " .id(exampleAssignmentPolicyId)\n", " .build();\n", "\n", "Response response = service.getV2Policy(options).execute();\n", "V2PolicyTemplateMetaData policy = response.getResult();\n", "\n", "System.out.println(policy.getTemplate());" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " id: examplePolicyId,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.getV2Policy(params);\n", " examplePolicyETag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}\n", "\n", "\n", "const params = {\n", " id: exampleAssignmentPolicyId,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.getV2Policy(params);\n", " examplePolicyETag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err)\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.get_v2_policy(id=example_policy_id)\n", "policy = response.get_result()\n", "\n", "global example_policy_etag\n", "example_policy_etag = response.get_headers().get(\"Etag\")\n", "\n", "print(json.dumps(policy, indent=2))" ] } ] } ] } } }, "delete": { "tags": [ "v2/Policies" ], "summary": "Delete a policy by ID", "operationId": "delete_v2_policy", "description": "Delete a policy by providing a policy ID. A policy cannot be deleted if the subject ID\ncontains a locked service ID.\nIf the subject of the policy is a locked service-id, the request will fail.\n", "responses": { "204": { "description": "Policy deletion successful." }, "400": { "description": "Policy was not valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a locked service id, cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam.policy.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policy.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v2/policies/$POLICY_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewDeleteV2PolicyOptions(\n", " examplePolicyID,\n", ")\n", "\n", "response, err := iamPolicyManagementService.DeleteV2Policy(options)\n", "if err != nil {\n", " panic(err)\n", "}" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " id: examplePolicyId,\n", "};\n", "\n", "try {\n", " await iamPolicyManagementService.deleteV2Policy(params);\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.delete_v2_policy(id=example_policy_id).get_result()\n", "\n", "print(json.dumps(response, indent=2))" ] } ] } ] } } } }, "/v2/roles": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Roles" ], "summary": "Get roles by filters", "operationId": "list_roles", "description": "Get roles based on the filters.\nWhile managing roles, you may want to retrieve roles\nand filter by usages.\nThis can be done through query parameters.\nCurrently, we only support the following attributes:\naccount_id, service_name, service_group_id, source_service_name and policy_type.\nBoth service_name and service_group_id attributes are mutually exclusive.\nOnly roles that match the filter and that the caller\nhas read access to are returned.\nIf the caller does not have read access to any roles\nan empty array is returned.\n", "parameters": [ { "name": "account_id", "in": "query", "description": "Optional account GUID in which the roles belong to.", "schema": { "type": "string" } }, { "name": "service_name", "in": "query", "description": "Optional name of IAM enabled service.", "schema": { "type": "string" }, "example": "iam-groups" }, { "name": "source_service_name", "in": "query", "description": "Optional name of source IAM enabled service.", "schema": { "type": "string" }, "example": "iam-groups" }, { "name": "policy_type", "in": "query", "description": "Optional Policy Type.", "schema": { "type": "string" }, "example": "authorization" }, { "name": "service_group_id", "in": "query", "description": "Optional id of service group.", "schema": { "type": "string" }, "example": "IAM" } ], "responses": { "200": { "description": "Roles retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleCollection" }, "examples": { "response": { "value": { "custom_roles": [ { "id": "12345678abcd1a2ba1b21234567890ab", "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example", "name": "Example", "display_name": "Example Role", "description": "Custom role for example", "service_name": "SERVICE_NAME", "account_id": "ACCOUNT_ID", "actions": [ "ACTION_ID_1", "ACTION_ID_2" ], "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab" } ], "service_roles": [ { "crn": "crn:v1:bluemix:public:iam::::serviceRole:Reader", "display_name": "Reader", "description": "Reader role for example", "actions": [ "ACTION_ID_1", "ACTION_ID_2" ] } ], "system_roles": [ { "crn": "crn:v1:bluemix:public:iam::::role:Viewer", "display_name": "Viewer", "description": "Viewer role for example", "actions": [ "ACTION_ID_1", "ACTION_ID_2" ] } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam.policy.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.role.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v2/roles' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewListRolesOptions()\n", "options.SetAccountID(exampleAccountID)\n", "\n", "roleList, response, err := iamPolicyManagementService.ListRoles(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(roleList, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListRolesOptions options = new ListRolesOptions.Builder()\n", " .accountId(exampleAccountId)\n", " .build();\n", "\n", "Response response = service.listRoles(options).execute();\n", "RoleCollection roleCollection = response.getResult();\n", "\n", "System.out.println(roleCollection);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " accountId: exampleAccountId,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.listRoles(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "role_list = iam_policy_management_service.list_roles(account_id=example_account_id).get_result()\n", "\n", "print(json.dumps(role_list, indent=2))" ] } ] } ] } } }, "post": { "tags": [ "Roles" ], "summary": "Create a role", "operationId": "create_role", "description": "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.\n", "x-codegen-request-body-name": "role", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolePostRequest" } } }, "description": "A role to be created.", "required": true }, "responses": { "201": { "description": "Role creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRole" }, "examples": { "response": { "value": { "id": "12345678abcd1a2ba1b21234567890ab", "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example", "name": "Example", "display_name": "Example Role", "description": "Custom role for example", "service_name": "SERVICE_NAME", "account_id": "ACCOUNT_ID", "actions": [ "ACTION_ID_1", "ACTION_ID_2" ], "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab" } } } } } }, "400": { "description": "Role input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "The role name conflicts with an existing system-defined role name. Choose a different name." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You don't have access to create the role. You must be assigned the Administrator role on the Role management service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested role. You must be assigned the Administrator role on the Role management service." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_conflict_error", "message": "This role name is already in use. Update the existing one or change the role name to be unique.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "role": "ROLE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum roles quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum roles quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.customRole.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.role.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v2/roles' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"Example\",\n", " \"display_name\": \"Example Role\",\n", " \"description\": \"Custom role for example\",\n", " \"account_id\": \"ACCOUNT_ID\",\n", " \"service_name\": \"SERVICE_NAME\",\n", " \"actions\":[\"ACTION_ID_1\", \"ACTION_ID_2\"]\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewCreateRoleOptions(\n", " \"IAM Groups read access\",\n", " []string{\"iam-groups.groups.read\"},\n", " \"ExampleRoleIAMGroups\",\n", " exampleAccountID,\n", " exampleServiceName,\n", ")\n", "\n", "customRole, response, err := iamPolicyManagementService.CreateRole(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(customRole, \"\", \" \")\n", "exampleCustomRoleID = *customRole.ID\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "CreateRoleOptions options = new CreateRoleOptions.Builder()\n", " .displayName(\"IAM Groups read access\")\n", " .actions(Arrays.asList(\"iam-groups.groups.read\"))\n", " .name(\"ExampleRoleIAMGroups\")\n", " .accountId(exampleAccountId)\n", " .serviceName(EXAMPLE_SERVICE_NAME)\n", " .build();\n", "\n", "Response response = service.createRole(options).execute();\n", "CustomRole customRole = response.getResult();\n", "\n", "exampleCustomRoleId = customRole.getId();\n", "\n", "System.out.println(customRole);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " displayName: exampleCustomRoleDipslayName,\n", " actions: ['iam-groups.groups.read'],\n", " name: 'ExampleRoleIAMGroups',\n", " accountId: exampleAccountId,\n", " serviceName: exampleServiceName,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.createRole(params);\n", " exampleCustomRoleId = res.result.id;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "custom_role = iam_policy_management_service.create_role(\n", " display_name='IAM Groups read access',\n", " actions=['iam-groups.groups.read'],\n", " name='ExampleRoleIAMGroups',\n", " account_id=example_account_id,\n", " service_name=example_service_name,\n", ").get_result()\n", "\n", "global example_custom_role_id\n", "example_custom_role_id = custom_role[\"id\"]\n", "\n", "print(json.dumps(custom_role, indent=2))" ] } ] } ] } } } }, "/v2/roles/{role_id}": { "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "The role ID.", "schema": { "type": "string" } } ], "put": { "tags": [ "Roles" ], "summary": "Update a role", "operationId": "replace_role", "description": "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.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a role and must match the ETag value of the existing role.\nThe Etag can be retrieved using the GET /v2/roles/{role_id} API and looking at the ETag response header.\n", "schema": { "type": "string" } } ], "x-codegen-request-body-name": "role", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } }, "description": "Updated role content to be saved.", "required": true }, "responses": { "200": { "description": "Role update successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRole" }, "examples": { "response": { "value": { "id": "12345678abcd1a2ba1b21234567890ab", "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example", "name": "Example", "display_name": "Example Role", "description": "Custom role for example", "service_name": "SERVICE_NAME", "account_id": "ACCOUNT_ID", "actions": [ "ACTION_ID_1", "ACTION_ID_2" ], "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab" } } } } } }, "400": { "description": "Role input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "In order to update an existing role, a rev value must be provided." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested role." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A role already exists with the same actions and account_id. You can update that role or delete it and create a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_conflict_error", "message": "The role wasn't updated.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "role": "ROLE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.customRole.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.role.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PUT \\\n", "'https://iam.cloud.ibm.com/v2/roles' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"display_name\": \"Example Role\",\n", " \"description\": \"Custom role for example\",\n", " \"actions\":[\"ACTION_ID_1\", \"ACTION_ID_2\"]\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "updatedRoleActions := []string{\"iam-groups.groups.read\", \"iam-groups.groups.list\"}\n", "\n", "options := iamPolicyManagementService.NewReplaceRoleOptions(\n", " exampleCustomRoleID,\n", " exampleCustomRoleETag,\n", " \"ExampleRoleIAMGroups\",\n", " updatedRoleActions,\n", ")\n", "\n", "customRole, response, err := iamPolicyManagementService.ReplaceRole(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(customRole, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "List updatedRoleActions = Arrays.asList(\"iam-groups.groups.read\", \"iam-groups.groups.list\");\n", "ReplaceRoleOptions options = new ReplaceRoleOptions.Builder()\n", " .roleId(exampleCustomRoleId)\n", " .ifMatch(exampleCustomRoleEtag)\n", " .displayName(\"IAM Groups read access\")\n", " .actions(updatedRoleActions)\n", " .build();\n", "\n", "Response response = service.replaceRole(options).execute();\n", "CustomRole customRole = response.getResult();\n", "\n", "System.out.println(customRole);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const updatedRoleActions = ['iam-groups.groups.read', 'iam-groups.groups.list'];\n", "const params = {\n", " roleId: exampleCustomRoleId,\n", " ifMatch: exampleCustomRoleEtag,\n", " displayName: exampleCustomRoleDipslayName,\n", " actions: updatedRoleActions,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.replaceRole(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "updated_role_actions = ['iam-groups.groups.read', 'iam-groups.groups.list']\n", "custom_role = iam_policy_management_service.replace_role(\n", " role_id=example_custom_role_id,\n", " if_match=example_custom_role_etag,\n", " actions=updated_role_actions,\n", " display_name='IAM Groups read access',\n", ").get_result()\n", "\n", "print(json.dumps(custom_role, indent=2))" ] } ] } ] } } }, "get": { "tags": [ "Roles" ], "summary": "Retrieve a role by ID", "operationId": "get_role", "description": "Retrieve a role by providing a role ID.", "responses": { "200": { "description": "Role retrieval successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the role.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRole" }, "examples": { "response": { "value": { "id": "12345678abcd1a2ba1b21234567890ab", "crn": "crn:v1:bluemix:public:iam-access-management::::customRole:Example", "name": "Example", "display_name": "Example Role", "description": "Custom role for example", "service_name": "SERVICE_NAME", "account_id": "ACCOUNT_ID", "actions": [ "ACTION_ID_1", "ACTION_ID_2" ], "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "href": "https://iam.cloud.ibm.com/v2/roles/12345678abcd1a2ba1b21234567890ab" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested role." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-events": { "events": [ { "name": "iam-am.role.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v2/roles/$ROLE_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewGetRoleOptions(\n", " exampleCustomRoleID,\n", ")\n", "\n", "customRole, response, err := iamPolicyManagementService.GetRole(options)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(customRole, \"\", \" \")\n", "exampleCustomRoleETag = response.Headers.Get(\"ETag\")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetRoleOptions options = new GetRoleOptions.Builder()\n", " .roleId(exampleCustomRoleId)\n", " .build();\n", "\n", "Response response = service.getRole(options).execute();\n", "CustomRole customRole = response.getResult();\n", "\n", "exampleCustomRoleEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(customRole);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " roleId: exampleCustomRoleId,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.getRole(params);\n", " exampleCustomRoleEtag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.get_role(role_id=example_custom_role_id)\n", "custom_role = response.get_result()\n", "\n", "global example_custom_role_etag\n", "example_custom_role_etag = response.get_headers().get(\"Etag\")\n", "\n", "print(json.dumps(custom_role, indent=2))" ] } ] } ] } } }, "delete": { "tags": [ "Roles" ], "summary": "Delete a role by ID", "operationId": "delete_role", "description": "Delete a role by providing a role ID.", "responses": { "204": { "description": "Role deletion successful." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested role." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.customRole.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.role.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v2/roles/$ROLE_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "options := iamPolicyManagementService.NewDeleteRoleOptions(\n", " exampleCustomRoleID,\n", ")\n", "\n", "response, err := iamPolicyManagementService.DeleteRole(options)\n", "if err != nil {\n", " panic(err)\n", "}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "DeleteRoleOptions options = new DeleteRoleOptions.Builder()\n", " .roleId(exampleCustomRoleId)\n", " .build();\n", "\n", "Response response = service.deleteRole(options).execute();" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " roleId: exampleCustomRoleId,\n", "};\n", "\n", "try {\n", " await iamPolicyManagementService.deleteRole(params);\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.delete_role(role_id=example_custom_role_id).get_result()\n", "\n", "print(json.dumps(response, indent=2))" ] } ] } ] } } } }, "/v1/policy_templates": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Policy templates" ], "summary": "List policy templates by attributes", "operationId": "list_policy_templates", "description": "List policy templates and filter by attributes by using query parameters.\nThe following attributes are supported:\n`account_id`, `policy_service_name`, `policy_service_type`, `policy_service_group_id` and `policy_type`.\n`account_id` is a required query parameter.\nThese attributes `policy_service_name`, `policy_service_type` and `policy_service_group_id` are mutually exclusive.\nOnly policy templates that have the specified attributes and that\nthe caller has read access to are returned.\nIf the caller does not have read access to any policy templates an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID that the policy templates belong to.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } }, { "name": "state", "in": "query", "description": "The policy template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "name": "name", "in": "query", "description": "The policy template name.", "schema": { "type": "string", "maxLength": 100, "minLength": 1 } }, { "name": "policy_service_type", "in": "query", "description": "Service type, Optional.", "schema": { "type": "string", "enum": [ "service", "platform_service" ] } }, { "name": "policy_service_name", "in": "query", "description": "Service name, Optional.", "schema": { "type": "string", "minLength": 1 } }, { "name": "policy_service_group_id", "in": "query", "description": "Service group id, Optional.", "schema": { "type": "string", "minLength": 1 } }, { "name": "policy_type", "in": "query", "description": "Policy type, Optional.", "schema": { "type": "string", "enum": [ "access", "authorization" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Policy Templates retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateCollection" }, "examples": { "response": { "value": { "policy_templates": [ { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "version": "1", "account_id": "000-000-000-001", "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates?account_id=$ACCOUNT_ID&state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "listPolicyTemplatesOptions := iamPolicyManagementService.NewListPolicyTemplatesOptions(\n", " exampleAccountID,\n", ")\n", "\n", "policyTemplateCollection, response, err := iamPolicyManagementService.ListPolicyTemplates(listPolicyTemplatesOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplateCollection, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListPolicyTemplatesOptions listPolicyTemplatesOptions = new ListPolicyTemplatesOptions.Builder()\n", " .accountId(exampleAccountId)\n", " .build();\n", "\n", "Response response = service.listPolicyTemplates(listPolicyTemplatesOptions).execute();\n", "PolicyTemplateCollection policyTemplateCollection = response.getResult();\n", "\n", "System.out.println(policyTemplateCollection);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " accountId: exampleAccountId,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.listPolicyTemplates(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.list_policy_templates(\n", " account_id=example_account_id,\n", ")\n", "policy_template_collection = response.get_result()\n", "\n", "print(json.dumps(policy_template_collection, indent=2))" ] } ] } ] } } }, "post": { "tags": [ "Policy templates" ], "summary": "Create a policy template", "operationId": "create_policy_template", "description": "Create a policy template. Policy templates define a policy without requiring a subject, and you can use them to grant access to multiple subjects.\n", "x-codegen-request-body-name": "policy_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateRequest" } } }, "description": "A policy template to be created.", "required": true }, "responses": { "201": { "description": "Policy Template creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateLimitData" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "version": "1", "account_id": "0000-0000-0001", "committed": false, "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "counts": { "template": { "current": 1, "limit": 100 }, "version": { "current": 1, "limit": 100 } }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "400": { "description": "Policy Template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy template." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy template already exists for the .... TBD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_template_conflict_error", "message": "Failed to create policy template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policyTemplate": "POLICY_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum policy templates quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum policy templates quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"IKSEditor\",\n", " \"description\": \"Grant Editor Role on SERVICE_NAME\",\n", " \"account_id\": \"ACCOUNT_ID\",\n", " \"policy\": {\n", " \"type\": \"access\",\n", " \"description\": \"Grant Editor Role on SERVICE_NAMEe\",\n", " \"control\": {\n", " \"grant\": {\n", " \"roles\": [\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Editor\"\n", " }\n", " ]\n", " }\n", " },\n", " \"resource\": {\n", " \"attributes\": [\n", " {\n", " \"key\": \"serviceName\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$SERVICE_NAME\"\n", " }\n", " ]\n", " },\n", " \"rule\" :{\n", " \"key\": \"{{environment.attributes.day_of_week}}\",\n", " \"operator\": \"dayOfWeekAnyOf\",\n", " \"value\": [\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"]\n", " },\n", " \"pattern\": \"time-based-conditions:weekly:all-day\"\n", " }\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "policyRole := &iampolicymanagementv1.Roles{\n", " RoleID: core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Viewer\"),\n", "}\n", "v2PolicyGrant := &iampolicymanagementv1.Grant{\n", " Roles: []iampolicymanagementv1.Roles{*policyRole},\n", "}\n", "v2PolicyControl := &iampolicymanagementv1.Control{\n", " Grant: v2PolicyGrant,\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"serviceName\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(\"iam-access-management\"),\n", "}\n", "policyResource := &iampolicymanagementv1.V2PolicyResource{\n", " Attributes: []iampolicymanagementv1.V2PolicyResourceAttribute{\n", " *serviceNameResourceAttribute},\n", "}\n", "\n", "templatePolicyModel := &iampolicymanagementv1.TemplatePolicy{\n", " Type: core.StringPtr(\"access\"),\n", " Description: core.StringPtr(\"Test Template\"),\n", " Resource: policyResource,\n", " Control: v2PolicyControl,\n", "}\n", "\n", "createPolicyTemplateOptions := iamPolicyManagementService.NewCreatePolicyTemplateOptions(\n", " examplePolicyTemplateName,\n", " exampleAccountID,\n", " templatePolicyModel,\n", ")\n", "\n", "policyTemplate, response, err := iamPolicyManagementService.CreatePolicyTemplate(createPolicyTemplateOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplate, \"\", \" \")\n", "examplePolicyTemplateID = *policyTemplate.ID\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "V2PolicyResourceAttribute v2PolicyResourceAttributeModel = new V2PolicyResourceAttribute.Builder()\n", " .key(\"serviceType\")\n", " .operator(\"stringEquals\")\n", " .value(\"service\")\n", " .build();\n", "V2PolicyResource v2PolicyResourceModel = new V2PolicyResource.Builder()\n", " .attributes(java.util.Arrays.asList(v2PolicyResourceAttributeModel))\n", " .build();\n", "Roles rolesModel = new Roles.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Viewer\")\n", " .build();\n", "Grant grantModel = new Grant.Builder()\n", " .roles(java.util.Arrays.asList(rolesModel))\n", " .build();\n", "Control controlModel = new Control.Builder()\n", " .grant(grantModel)\n", " .build();\n", "TemplatePolicy templatePolicyModel = new TemplatePolicy.Builder()\n", " .type(\"access\")\n", " .resource(v2PolicyResourceModel)\n", " .control(controlModel)\n", " .build();\n", "CreatePolicyTemplateOptions createPolicyTemplateOptions = new CreatePolicyTemplateOptions.Builder()\n", " .name(\"SDKExamplesTest\")\n", " .accountId(exampleAccountId)\n", " .policy(templatePolicyModel)\n", " .build();\n", "\n", "Response response = service.createPolicyTemplate(createPolicyTemplateOptions).execute();\n", "PolicyTemplateLimitData policyTemplate = response.getResult();\n", "\n", "exampleTemplateId = policyTemplate.getId();\n", "exampleTemplateVersion = policyTemplate.getVersion();\n", "\n", "System.out.println(policyTemplate);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "// Request models needed by this operation.\n", "\n", "// V2PolicyResourceAttribute\n", "const v2PolicyResourceAttributeModel = {\n", " key: 'serviceType',\n", " operator: 'stringEquals',\n", " value: 'service',\n", "};\n", "\n", "// V2PolicyResource\n", "const v2PolicyResourceModel = {\n", " attributes: [v2PolicyResourceAttributeModel],\n", "};\n", "\n", "// Roles\n", "const rolesModel = {\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Viewer',\n", "};\n", "\n", "// Grant\n", "const grantModel = {\n", " roles: [rolesModel],\n", "};\n", "\n", "// Control\n", "const controlModel = {\n", " grant: grantModel,\n", "};\n", "\n", "// TemplatePolicy\n", "const templatePolicyModel = {\n", " type: 'access',\n", " resource: v2PolicyResourceModel,\n", " control: controlModel,\n", "};\n", "\n", "const params = {\n", " name: 'SDKNodeExampleTemplate',\n", " accountId: exampleAccountId,\n", " policy: templatePolicyModel,\n", "};\n", "\n", "try {\n", " const res = await iamPolicyManagementService.createPolicyTemplate(params);\n", " exampleTemplateId = res.result.id;\n", " exampleTemplateVersion = res.result.version;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "v2_policy_resource_attribute_model = {\n", " 'key': 'serviceType',\n", " 'operator': 'stringEquals',\n", " 'value': 'service',\n", "}\n", "\n", "v2_policy_resource_model = {\n", " 'attributes': [v2_policy_resource_attribute_model],\n", "}\n", "\n", "roles_model = {\n", " 'role_id': 'crn:v1:bluemix:public:iam::::role:Viewer',\n", "}\n", "\n", "grant_model = {\n", " 'roles': [roles_model],\n", "}\n", "\n", "control_model = {\n", " 'grant': grant_model,\n", "}\n", "\n", "template_policy_model = {\n", " 'type': 'access',\n", " 'resource': v2_policy_resource_model,\n", " 'control': control_model,\n", "}\n", "\n", "response = iam_policy_management_service.create_policy_template(\n", " name='SDKExamplesTest',\n", " account_id=example_account_id,\n", " policy=template_policy_model,\n", ")\n", "policy_template = response.get_result()\n", "\n", "global example_template_id\n", "example_template_id = policy_template['id']\n", "global example_template_version\n", "example_template_version = policy_template['version']\n", "\n", "print(json.dumps(policy_template, indent=2))" ] } ] } ] } } } }, "/v1/policy_templates/{policy_template_id}": { "parameters": [ { "name": "policy_template_id", "in": "path", "required": true, "description": "The policy template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 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}$" } } ], "get": { "tags": [ "Policy templates" ], "summary": "Retrieve latest version of a policy template", "operationId": "get_policy_template", "description": "Retrieve the latest version of a policy template by providing a policy template ID.", "parameters": [ { "name": "state", "in": "query", "description": "The policy template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } } ], "responses": { "200": { "description": "Policy Template retrieval successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the policy template.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplate" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "account_id": "0000-0000-0000-0001", "version": "2", "committed": false, "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab/versions/2", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID&state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "getPolicyTemplateOptions := iamPolicyManagementService.NewGetPolicyTemplateOptions(\n", " examplePolicyTemplateID,\n", ")\n", "\n", "policyTemplate, response, err := iamPolicyManagementService.GetPolicyTemplate(getPolicyTemplateOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplate, \"\", \" \")\n", "examplePolicyTemplateETag = response.GetHeaders().Get(\"ETag\")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetPolicyTemplateOptions getPolicyTemplateOptions = new GetPolicyTemplateOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .build();\n", "\n", "Response response = service.getPolicyTemplate(getPolicyTemplateOptions).execute();\n", "PolicyTemplate policyTemplate = response.getResult();\n", "\n", "exampleTemplateEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(policyTemplate);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyTemplateId: exampleTemplateId,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.getPolicyTemplate(params);\n", " exampleTemplateEtag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "print('example_template_id: ', example_template_id)\n", "response = iam_policy_management_service.get_policy_template(\n", " policy_template_id=example_template_id,\n", ")\n", "policy_template = response.get_result()\n", "\n", "global example_template_etag\n", "example_template_etag = response.get_headers().get(\"Etag\")\n", "\n", "print(json.dumps(policy_template, indent=2))" ] } ] } ] } } }, "delete": { "tags": [ "Policy templates" ], "summary": "Delete a policy template", "operationId": "delete_policy_template", "description": "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.\n", "responses": { "204": { "description": "Policy Template deletion successful." }, "400": { "description": "Policy Template was not valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a version assigned to an account, cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy template version." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "deletePolicyTemplateOptions := iamPolicyManagementService.NewDeletePolicyTemplateOptions(\n", " examplePolicyTemplateID,\n", ")\n", "\n", "response, err := iamPolicyManagementService.DeletePolicyTemplate(deletePolicyTemplateOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "if response.StatusCode != 204 {\n", " fmt.Printf(\"\\nUnexpected response status code received from DeletePolicyTemplate(): %d\\n\", response.StatusCode)\n", "}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "DeletePolicyTemplateOptions deletePolicyTemplateOptions = new DeletePolicyTemplateOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .build();\n", "\n", "Response response = service.deletePolicyTemplate(deletePolicyTemplateOptions).execute();" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyTemplateId: exampleTemplateId,\n", "};\n", "\n", "try {\n", " await iamPolicyManagementService.deletePolicyTemplate(params);\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.delete_policy_template(\n", " policy_template_id=example_template_id,\n", ")" ] } ] } ] } } } }, "/v1/policy_templates/{policy_template_id}/versions": { "parameters": [ { "name": "policy_template_id", "in": "path", "required": true, "description": "The policy template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 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}$" } } ], "post": { "tags": [ "Policy templates" ], "summary": "Create a new policy template version", "operationId": "create_policy_template_version", "description": "Create a new version of a policy template. Use this if you need to make updates to a policy template that is committed.\n", "x-codegen-request-body-name": "policy_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateVersionRequest" } } }, "description": "A policy template to be created.", "required": true }, "responses": { "201": { "description": "Policy Template creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateLimitData" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "account_id": "0000-0000-0000-0001", "version": "2", "committed": false, "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "counts": { "template": { "current": 1, "limit": 100 }, "version": { "current": 1, "limit": 100 } }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab/versions/2", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "400": { "description": "Policy Template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy template." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy template already exists for the .... TBD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_template_conflict_error", "message": "Failed to create policy template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policyTemplate": "POLICY_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum policies templates quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum policy templates quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/policy_template/$TEMPLATE_ID/versions' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"IKSEditor\",\n", " \"description\": \"Grant Editor Role on SERVICE_NAME\",\n", " \"account_id\": \"ACCOUNT_ID\",\n", " \"policy\": {\n", " \"type\": \"access\",\n", " \"description\": \"Grant Editor Role on SERVICE_NAMEe\",\n", " \"control\": {\n", " \"grant\": {\n", " \"roles\": [\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Editor\"\n", " }\n", " ]\n", " }\n", " },\n", " \"resource\": {\n", " \"attributes\": [\n", " {\n", " \"key\": \"serviceName\",\n", " \"operator\": \"stringEquals\",\n", " \"value\": \"$SERVICE_NAME\"\n", " }\n", " ]\n", " },\n", " \"rule\" :{\n", " \"key\": \"{{environment.attributes.day_of_week}}\",\n", " \"operator\": \"dayOfWeekAnyOf\",\n", " \"value\": [\"1+00:00\", \"2+00:00\", \"3+00:00\", \"4+00:00\", \"5+00:00\"]\n", " },\n", " \"pattern\": \"time-based-conditions:weekly:all-day\"\n", " }\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "v2PolicyGrant := &iampolicymanagementv1.Grant{\n", " Roles: []iampolicymanagementv1.Roles{\n", " {core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Viewer\")},\n", " {core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Administrator\")},\n", " },\n", "}\n", "\n", "v2PolicyControl := &iampolicymanagementv1.Control{\n", " Grant: v2PolicyGrant,\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"serviceName\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(\"watson\"),\n", "}\n", "policyResource := &iampolicymanagementv1.V2PolicyResource{\n", " Attributes: []iampolicymanagementv1.V2PolicyResourceAttribute{\n", " *serviceNameResourceAttribute},\n", "}\n", "\n", "templatePolicyModel := &iampolicymanagementv1.TemplatePolicy{\n", " Type: core.StringPtr(\"access\"),\n", " Description: core.StringPtr(\"Test Template v2\"),\n", " Resource: policyResource,\n", " Control: v2PolicyControl,\n", "}\n", "\n", "createPolicyTemplateVersionOptions := iamPolicyManagementService.NewCreatePolicyTemplateVersionOptions(\n", " examplePolicyTemplateID,\n", " templatePolicyModel,\n", ")\n", "\n", "policyTemplate, response, err := iamPolicyManagementService.CreatePolicyTemplateVersion(createPolicyTemplateVersionOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplate, \"\", \" \")\n", "examplePolicyTemplateETag = response.GetHeaders().Get(\"ETag\")\n", "examplePolicyTemplateVersion = *policyTemplate.Version\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "V2PolicyResourceAttribute v2PolicyResourceAttributeModel = new V2PolicyResourceAttribute.Builder()\n", " .key(\"serviceType\")\n", " .operator(\"stringEquals\")\n", " .value(\"service\")\n", " .build();\n", "V2PolicyResource v2PolicyResourceModel = new V2PolicyResource.Builder()\n", " .attributes(java.util.Arrays.asList(v2PolicyResourceAttributeModel))\n", " .build();\n", "Roles rolesModel = new Roles.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Viewer\")\n", " .build();\n", "Grant grantModel = new Grant.Builder()\n", " .roles(java.util.Arrays.asList(rolesModel))\n", " .build();\n", "Control controlModel = new Control.Builder()\n", " .grant(grantModel)\n", " .build();\n", "TemplatePolicy templatePolicyModel = new TemplatePolicy.Builder()\n", " .type(\"access\")\n", " .resource(v2PolicyResourceModel)\n", " .control(controlModel)\n", " .build();\n", "CreatePolicyTemplateVersionOptions createPolicyTemplateVersionOptions = new CreatePolicyTemplateVersionOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .policy(templatePolicyModel)\n", " .build();\n", "\n", "Response response = service.createPolicyTemplateVersion(createPolicyTemplateVersionOptions).execute();\n", "PolicyTemplateLimitData policyTemplate = response.getResult();\n", "\n", "System.out.println(policyTemplate);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "// Request models needed by this operation.\n", "\n", "// V2PolicyResourceAttribute\n", "const v2PolicyResourceAttributeModel = {\n", " key: 'serviceType',\n", " operator: 'stringEquals',\n", " value: 'service',\n", "};\n", "\n", "// V2PolicyResource\n", "const v2PolicyResourceModel = {\n", " attributes: [v2PolicyResourceAttributeModel],\n", "};\n", "\n", "// Roles\n", "const rolesModel = {\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Viewer',\n", "};\n", "\n", "// Grant\n", "const grantModel = {\n", " roles: [rolesModel],\n", "};\n", "\n", "// Control\n", "const controlModel = {\n", " grant: grantModel,\n", "};\n", "\n", "// TemplatePolicy\n", "const templatePolicyModel = {\n", " type: 'access',\n", " resource: v2PolicyResourceModel,\n", " control: controlModel,\n", "};\n", "\n", "const params = {\n", " policyTemplateId: exampleTemplateId,\n", " policy: templatePolicyModel,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.createPolicyTemplateVersion(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "v2_policy_resource_attribute_model = {\n", " 'key': 'serviceType',\n", " 'operator': 'stringEquals',\n", " 'value': 'service',\n", "}\n", "\n", "v2_policy_resource_model = {\n", " 'attributes': [v2_policy_resource_attribute_model],\n", "}\n", "\n", "roles_model = {\n", " 'role_id': 'crn:v1:bluemix:public:iam::::role:Viewer',\n", "}\n", "\n", "grant_model = {\n", " 'roles': [roles_model],\n", "}\n", "\n", "control_model = {\n", " 'grant': grant_model,\n", "}\n", "\n", "template_policy_model = {\n", " 'type': 'access',\n", " 'resource': v2_policy_resource_model,\n", " 'control': control_model,\n", "}\n", "\n", "response = iam_policy_management_service.create_policy_template_version(\n", " policy_template_id=example_template_id,\n", " policy=template_policy_model,\n", ")\n", "policy_template = response.get_result()\n", "\n", "print(json.dumps(policy_template, indent=2))" ] } ] } ] } } }, "get": { "tags": [ "Policy templates" ], "summary": "Retrieve policy template versions", "operationId": "list_policy_template_versions", "description": "Retrieve the versions of a policy template by providing a policy template ID.", "parameters": [ { "name": "state", "in": "query", "description": "The policy template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Policy Template versions retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateVersionsCollection" }, "examples": { "response": { "value": { "versions": [ { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "account_id": "0000-0000-0000-0001", "version": "2", "committed": false, "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab/versions/2", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID/versions&state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "listPolicyTemplateVersionsOptions := iamPolicyManagementService.NewListPolicyTemplateVersionsOptions(\n", " examplePolicyTemplateID,\n", ")\n", "\n", "policyTemplateVersionsCollection, response, err := iamPolicyManagementService.ListPolicyTemplateVersions(listPolicyTemplateVersionsOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplateVersionsCollection, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListPolicyTemplateVersionsOptions listPolicyTemplateVersionsOptions = new ListPolicyTemplateVersionsOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .build();\n", "\n", "Response response = service.listPolicyTemplateVersions(listPolicyTemplateVersionsOptions).execute();\n", "PolicyTemplateVersionsCollection policyTemplateVersionsCollection = response.getResult();\n", "\n", "System.out.println(policyTemplateVersionsCollection);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyTemplateId: exampleTemplateId,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.listPolicyTemplateVersions(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.list_policy_template_versions(\n", " policy_template_id=example_template_id,\n", ")\n", "policy_template_versions_collection = response.get_result()\n", "\n", "print(json.dumps(policy_template_versions_collection, indent=2))" ] } ] } ] } } } }, "/v1/policy_templates/{policy_template_id}/versions/{version}": { "parameters": [ { "name": "policy_template_id", "in": "path", "required": true, "description": "The policy template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 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}$" } }, { "name": "version", "in": "path", "required": true, "description": "The policy template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } ], "put": { "tags": [ "Policy templates" ], "summary": "Update a policy template version", "operationId": "replace_policy_template", "description": "Update a specific version of a policy template. You can use this only if the version isn't committed.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a policy template version and must match the Etag value of the existing policy template version.\nThe Etag can be retrieved using the GET /v1/policy_templates/{policy_template_id}/versions/{version} API and looking at the Etag response header.\n", "schema": { "type": "string", "minLength": 1 } } ], "x-codegen-request-body-name": "policy_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateVersionRequest" } } }, "description": "Updated policy template content to be saved.", "required": true }, "responses": { "200": { "description": "Policy Template version update successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplate" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "account_id": "0000-0000-0000-0001", "version": "2", "committed": false, "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab/versions/2", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "400": { "description": "Policy template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "A policy's type cannot be updated. Create a new policy template and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy template already exists ... TBD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_template_conflict_error", "message": "Failed to update policy template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy_template": "POLICY_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PUT \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"type\": \"access\",\n", " \"description\": \"Viewer role for for all instances of SERVICE_NAME in the account.\",\n", " \"subjects\": {\n", " \"attributes\": [\n", " {\n", " \"name\": \"iam_id\",\n", " \"value\": \"$USER_ID\"\n", " }\n", " ]\n", " },\n", " \"roles\":[\n", " {\n", " \"role_id\": \"crn:v1:bluemix:public:iam::::role:Viewer\"\n", " }\n", " ],\n", " \"resources\": {\n", " \"attributes\": [\n", " {\n", " \"name\": \"accountId\",\n", " \"value\": \"$ACCOUNT_ID\"\n", " },\n", " {\n", " \"name\": \"serviceName\",\n", " \"value\": \"$SERVICE_NAME\"\n", " }\n", " ]\n", " }\n", "}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "v2PolicyGrant := &iampolicymanagementv1.Grant{\n", " Roles: []iampolicymanagementv1.Roles{\n", " {core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Viewer\")},\n", " {core.StringPtr(\"crn:v1:bluemix:public:iam::::role:Administrator\")},\n", " },\n", "}\n", "\n", "v2PolicyControl := &iampolicymanagementv1.Control{\n", " Grant: v2PolicyGrant,\n", "}\n", "serviceNameResourceAttribute := &iampolicymanagementv1.V2PolicyResourceAttribute{\n", " Key: core.StringPtr(\"serviceName\"),\n", " Operator: core.StringPtr(\"stringEquals\"),\n", " Value: core.StringPtr(\"watson\"),\n", "}\n", "policyResource := &iampolicymanagementv1.V2PolicyResource{\n", " Attributes: []iampolicymanagementv1.V2PolicyResourceAttribute{\n", " *serviceNameResourceAttribute},\n", "}\n", "\n", "templatePolicyModel := &iampolicymanagementv1.TemplatePolicy{\n", " Type: core.StringPtr(\"access\"),\n", " Description: core.StringPtr(\"Test Template v2\"),\n", " Resource: policyResource,\n", " Control: v2PolicyControl,\n", "}\n", "\n", "replacePolicyTemplateOptions := iamPolicyManagementService.NewReplacePolicyTemplateOptions(\n", " examplePolicyTemplateID,\n", " examplePolicyTemplateVersion,\n", " examplePolicyTemplateETag,\n", " templatePolicyModel,\n", ")\n", "\n", "policyTemplate, response, err := iamPolicyManagementService.ReplacePolicyTemplate(replacePolicyTemplateOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplate, \"\", \" \")\n", "examplePolicyTemplateVersion = *policyTemplate.Version\n", "examplePolicyTemplateETag = response.GetHeaders().Get(\"ETag\")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "V2PolicyResourceAttribute v2PolicyResourceAttributeModel = new V2PolicyResourceAttribute.Builder()\n", " .key(\"serviceType\")\n", " .operator(\"stringEquals\")\n", " .value(\"service\")\n", " .build();\n", "V2PolicyResource v2PolicyResourceModel = new V2PolicyResource.Builder()\n", " .attributes(java.util.Arrays.asList(v2PolicyResourceAttributeModel))\n", " .build();\n", "Roles rolesModel = new Roles.Builder()\n", " .roleId(\"crn:v1:bluemix:public:iam::::role:Editor\")\n", " .build();\n", "Grant grantModel = new Grant.Builder()\n", " .roles(java.util.Arrays.asList(rolesModel))\n", " .build();\n", "Control controlModel = new Control.Builder()\n", " .grant(grantModel)\n", " .build();\n", "TemplatePolicy templatePolicyModel = new TemplatePolicy.Builder()\n", " .type(\"access\")\n", " .resource(v2PolicyResourceModel)\n", " .control(controlModel)\n", " .build();\n", "ReplacePolicyTemplateOptions replacePolicyTemplateOptions = new ReplacePolicyTemplateOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .version(exampleTemplateVersion)\n", " .ifMatch(exampleTemplateEtag)\n", " .policy(templatePolicyModel)\n", " .build();\n", "\n", "Response response = service.replacePolicyTemplate(replacePolicyTemplateOptions).execute();\n", "PolicyTemplate policyTemplate = response.getResult();\n", "\n", "System.out.println(policyTemplate);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "// Request models needed by this operation.\n", "\n", "// V2PolicyResourceAttribute\n", "const v2PolicyResourceAttributeModel = {\n", " key: 'serviceType',\n", " operator: 'stringEquals',\n", " value: 'service',\n", "};\n", "\n", "// V2PolicyResource\n", "const v2PolicyResourceModel = {\n", " attributes: [v2PolicyResourceAttributeModel],\n", "};\n", "\n", "// Roles\n", "const rolesModel = {\n", " role_id: 'crn:v1:bluemix:public:iam::::role:Editor',\n", "};\n", "\n", "// Grant\n", "const grantModel = {\n", " roles: [rolesModel],\n", "};\n", "\n", "// Control\n", "const controlModel = {\n", " grant: grantModel,\n", "};\n", "\n", "// TemplatePolicy\n", "const templatePolicyModel = {\n", " type: 'access',\n", " resource: v2PolicyResourceModel,\n", " control: controlModel,\n", "};\n", "\n", "const params = {\n", " policyTemplateId: exampleTemplateId,\n", " version: exampleTemplateVersion,\n", " ifMatch: exampleTemplateEtag,\n", " policy: templatePolicyModel,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.replacePolicyTemplate(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "v2_policy_resource_attribute_model = {\n", " 'key': 'serviceType',\n", " 'operator': 'stringEquals',\n", " 'value': 'service',\n", "}\n", "\n", "v2_policy_resource_model = {\n", " 'attributes': [v2_policy_resource_attribute_model],\n", "}\n", "\n", "roles_model = {\n", " 'role_id': 'crn:v1:bluemix:public:iam::::role:Editor',\n", "}\n", "\n", "grant_model = {\n", " 'roles': [roles_model],\n", "}\n", "\n", "control_model = {\n", " 'grant': grant_model,\n", "}\n", "\n", "template_policy_model = {\n", " 'type': 'access',\n", " 'resource': v2_policy_resource_model,\n", " 'control': control_model,\n", "}\n", "\n", "response = iam_policy_management_service.replace_policy_template(\n", " policy_template_id=example_template_id,\n", " version=example_template_version,\n", " if_match=example_template_etag,\n", " policy=template_policy_model,\n", ")\n", "policy_template = response.get_result()\n", "\n", "print(json.dumps(policy_template, indent=2))" ] } ] } ] } } }, "delete": { "tags": [ "Policy templates" ], "summary": "Delete a policy template version", "operationId": "delete_policy_template_version", "description": "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.\n", "responses": { "204": { "description": "Policy Template deletion successful." }, "400": { "description": "Policy Template was not valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a version assigned to an account, cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy template version." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "deletePolicyTemplateVersionOptions := iamPolicyManagementService.NewDeletePolicyTemplateVersionOptions(\n", " examplePolicyTemplateID,\n", " examplePolicyTemplateVersion,\n", ")\n", "\n", "response, err := iamPolicyManagementService.DeletePolicyTemplateVersion(deletePolicyTemplateVersionOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "if response.StatusCode != 204 {\n", " fmt.Printf(\"\\nUnexpected response status code received from DeletePolicyTemplateVersion(): %d\\n\", response.StatusCode)\n", "}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "DeletePolicyTemplateVersionOptions deletePolicyTemplateVersionOptions = new DeletePolicyTemplateVersionOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .version(exampleTemplateVersion)\n", " .build();\n", "\n", "Response response = service.deletePolicyTemplateVersion(deletePolicyTemplateVersionOptions).execute();" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyTemplateId: exampleTemplateId,\n", " version: exampleTemplateVersion,\n", "};\n", "\n", "try {\n", " await iamPolicyManagementService.deletePolicyTemplateVersion(params);\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ] } } }, "get": { "tags": [ "Policy templates" ], "summary": "Retrieve a policy template version", "operationId": "get_policy_template_version", "description": "Retrieve a policy template by providing a policy template ID and version number.", "responses": { "200": { "description": "Policy Template retrieval successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the policy template.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplate" }, "examples": { "response": { "value": { "id": "12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Service Viewer template", "description": "Viewer role for all instances of SERVICE_NAME in the account.", "account_id": "0000-0000-0000-0001", "version": "2", "committed": false, "policy": { "type": "access", "description": "Viewer role access for all instances of key protect in the account during business hours.", "control": { "grant": { "roles": [ { "role_id": "crn:v1:bluemix:public:iam::::role:Viewer" } ], "role_template_references": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" } ] } }, "resource": { "attributes": [ { "key": "serviceName", "operator": "stringEquals", "value": "kms" } ] }, "rule": { "operator": "and", "conditions": [ { "key": "{{environment.attributes.day_of_week}}", "operator": "dayOfWeekAnyOf", "value": [ "1+00:00", "2+00:00", "3+00:00", "4+00:00", "5+00:00" ] }, { "key": "{{environment.attributes.current_time}}", "operator": "timeGreaterThanOrEquals", "value": "09:00:00+00:00" }, { "key": "{{environment.attributes.current_time}}", "operator": "timeLessThanOrEquals", "value": "17:00:00+00:00" } ] }, "pattern": "time-based-conditions:weekly:custom-hours" }, "href": "https://iam.cloud.ibm.com/v1/policy_templates/12345678-abcd-1a2b-a1b2-1234567890ab/versions/2", "created_at": "2018-08-30T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2018-08-30T14:09:09.907Z", "last_modified_by_id": "USER_ID", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "getPolicyTemplateVersionOptions := iamPolicyManagementService.NewGetPolicyTemplateVersionOptions(\n", " examplePolicyTemplateID,\n", " examplePolicyTemplateVersion,\n", ")\n", "\n", "policyTemplate, response, err := iamPolicyManagementService.GetPolicyTemplateVersion(getPolicyTemplateVersionOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyTemplate, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetPolicyTemplateVersionOptions getPolicyTemplateVersionOptions = new GetPolicyTemplateVersionOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .version(exampleTemplateVersion)\n", " .build();\n", "\n", "Response response = service.getPolicyTemplateVersion(getPolicyTemplateVersionOptions).execute();\n", "PolicyTemplate policyTemplate = response.getResult();\n", "\n", "exampleTemplateEtag = response.getHeaders().values(\"Etag\").get(0);\n", "\n", "System.out.println(policyTemplate);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyTemplateId: exampleTemplateId,\n", " version: exampleTemplateVersion,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.getPolicyTemplateVersion(params);\n", " exampleTemplateEtag = res.headers.etag;\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.get_policy_template_version(\n", " policy_template_id=example_template_id,\n", " version=example_template_version,\n", ")\n", "policy_template = response.get_result()\n", "\n", "global example_template_etag\n", "example_template_etag = response.get_headers().get(\"Etag\")\n", "\n", "print(json.dumps(policy_template, indent=2))" ] } ] } ] } } } }, "/v1/policy_templates/{policy_template_id}/versions/{version}/commit": { "parameters": [ { "name": "policy_template_id", "in": "path", "required": true, "description": "The policy template ID.", "schema": { "type": "string", "minLength": 1, "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}$", "maxLength": 51 } }, { "name": "version", "in": "path", "required": true, "description": "The policy template version.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9]*$", "maxLength": 2 } } ], "post": { "tags": [ "Policy templates" ], "summary": "Commit a policy template version", "operationId": "commit_policy_template", "description": "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.\n", "x-codegen-request-body-name": "policy", "responses": { "204": { "description": "Policy Template version update successful." }, "400": { "description": "Policy template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "A policy's type cannot be updated. Create a new policy template and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the policy template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested policy template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-template.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyTemplate.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/policy_templates/$TEMPLATE_ID/versions/$TEMLPATE_VERSION/commit' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "commitPolicyTemplateOptions := iamPolicyManagementService.NewCommitPolicyTemplateOptions(\n", " examplePolicyTemplateID,\n", " examplePolicyTemplateVersion,\n", ")\n", "\n", "response, err := iamPolicyManagementService.CommitPolicyTemplate(commitPolicyTemplateOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "if response.StatusCode != 204 {\n", " fmt.Printf(\"\\nUnexpected response status code received from CommitPolicyTemplate(): %d\\n\", response.StatusCode)\n", "}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "CommitPolicyTemplateOptions commitPolicyTemplateOptions = new CommitPolicyTemplateOptions.Builder()\n", " .policyTemplateId(exampleTemplateId)\n", " .version(exampleTemplateVersion)\n", " .build();\n", "\n", "Response response = service.commitPolicyTemplate(commitPolicyTemplateOptions).execute();" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " policyTemplateId: exampleTemplateId,\n", " version: exampleTemplateVersion,\n", "};\n", "\n", "try {\n", " await iamPolicyManagementService.commitPolicyTemplate(params);\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.commit_policy_template(\n", " policy_template_id=example_template_id,\n", " version=example_template_version,\n", ")" ] } ] } ] } } } }, "/v1/policy_assignments": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" }, { "name": "version", "in": "query", "description": "specify version of response body format", "required": true, "schema": { "type": "string", "minLength": 1, "enum": [ "1.0" ] } } ], "get": { "tags": [ "Policy assignments" ], "summary": "Get policy template assignments", "operationId": "list_policy_assignments", "description": "Get policy template assignments by attributes.\nThe following attributes are supported:\n`account_id`, `template_id`, `template_version`, `sort`.\n`account_id` is a required query parameter.\nOnly policy template assignments that have the specified attributes and that\nthe caller has read access to are returned.\nIf the caller does not have read access to any policy template assignments an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID in which the policies belong to.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } }, { "name": "template_id", "in": "query", "description": "Optional template id.", "schema": { "type": "string", "minLength": 1, "maxLength": 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}$" } }, { "name": "template_version", "in": "query", "description": "Optional policy template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Policy template assignments retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateAssignmentCollection" }, "examples": { "response": { "value": { "assignments": [ { "id": "", "account_id": "", "template": { "id": "policyTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "AccountId" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "Account-1" }, "policy": { "resource_created": { "id": "0000-0000-0000-0001" }, "status": "succeeded" } } ], "href": "https://iam.cloud.ibm.com/v1/policy_assignments/1122-222", "created_at": "2022-07-23T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2022-07-23T14:09:09.907Z", "last_modified_by_id": "USER_ID" } ] } } } } } }, "400": { "description": "The request that you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-assignment.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyAssignment.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policy_assignments?account_id=$ACCOUNT_ID&version=1.0' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "listPolicyAssignmentsOptions := iamPolicyManagementService.NewListPolicyAssignmentsOptions(\n", " exampleAccountID,\n", ")\n", "\n", "polcyTemplateAssignmentCollection, response, err := iamPolicyManagementService.ListPolicyAssignments(listPolicyAssignmentsOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(polcyTemplateAssignmentCollection, \"\", \" \")\n", "testPolicyAssignmentId = *polcyTemplateAssignmentCollection.Assignments[0].ID\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListPolicyAssignmentsOptions listPolicyAssignmentsOptions = new ListPolicyAssignmentsOptions.Builder()\n", " .accountId(exampleAccountId)\n", " .build();\n", "\n", "Response response = service.listPolicyAssignments(listPolicyAssignmentsOptions).execute();\n", "PolicyTemplateAssignmentCollection polcyTemplateAssignmentCollection = response.getResult();\n", "\n", "exampleAssignmentId = polcyTemplateAssignmentCollection.getAssignments().get(0).getId();\n", "\n", "System.out.println(polcyTemplateAssignmentCollection);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " accountId: exampleAccountId,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.listPolicyAssignments(params);\n", " exampleAssignmentId = res.result.assignments[0].id\n", " console.log(JSON.stringify(res.result, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.list_policy_assignments(\n", " account_id=example_account_id,\n", ")\n", "polcy_template_assignment_collection = response.get_result()\n", "\n", "global example_assignment_id\n", "example_assignment_id = polcy_template_assignment_collection['assignments'][0]['id']\n", "\n", "print(json.dumps(polcy_template_assignment_collection, indent=2))" ] } ] } ] } } }, "post": { "tags": [ "Policy assignments" ], "summary": "Create a policy authorization template assignment", "operationId": "create_policy_template_assignment", "description": "Assign a policy template to child accounts and account groups. This creates the policy in the accounts and account groups that you specify.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAssignmentV1Request" } } }, "description": "A policy assignment to be created.", "required": true }, "responses": { "201": { "description": "Policy assignment creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAssignmentV1Collection" }, "examples": { "response": { "value": { "assignments": [ { "id": "", "account_id": "", "template": { "id": "policyTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" }, "target": { "type": "Account", "id": "AccountId" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "Account-1" }, "policy": { "resource_created": { "id": "0000-0000-0000-0001" }, "status": "succeeded" } } ], "href": "https://iam.cloud.ibm.com/v1/policy_assignments/{assignment_id}", "created_at": "2022-07-23T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2022-07-23T14:09:09.907Z", "last_modified_by_id": "USER_ID" } ] } } } } } }, "400": { "description": "Policy assignment input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested policy." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A policy assignment exists for the given template ID, version, and target account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_assignment_conflict_error", "message": "Failed to create policy assignment.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "policy_assignment": "POLICY_ASSIGNMENT" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-assignment.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyAssignment.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/policy_assignments?version=1.0' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"templates\": [{\n", " \"id\": \"template_id\",\n", " \"version\": \"template_version\"\n", " }],\n", " \"target\": {\n", " \"id\": \"target account\",\n", " \"type\": \"target type\"\n", " }\n", "}'" ] } ] } ] } } } }, "/v1/policy_assignments/{assignment_id}": { "parameters": [ { "name": "assignment_id", "in": "path", "required": true, "description": "The policy template assignment ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 53 } } ], "get": { "tags": [ "Policy assignments" ], "parameters": [ { "name": "version", "in": "query", "description": "specify version of response body format", "required": true, "schema": { "type": "string", "minLength": 1, "enum": [ "1.0" ] } } ], "summary": "Retrieve a policy assignment", "operationId": "get_policy_assignment", "description": "Retrieve a policy template assignment by providing a policy assignment ID.", "responses": { "200": { "description": "Policy assignment retrieval successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the policy.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyTemplateAssignmentItems" }, "examples": { "response": { "value": { "id": "", "account_id": "", "template": { "id": "policyTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" }, "target": { "type": "Account", "id": "AccountId" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "Account-1" }, "policy": { "resource_created": { "id": "0000-0000-0000-0001" }, "status": "succeeded" } } ], "href": "https://iam.cloud.ibm.com/v1/policy_assignments/{assignment_id}", "created_at": "2022-07-23T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2022-07-23T14:09:09.907Z", "last_modified_by_id": "USER_ID" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyAssignmentNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-assignment.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyAssignment.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/policy_assignments/$POLICY_ASSIGNMENT_ID?version=1.0' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "getPolicyAssignmentOptions := iamPolicyManagementService.NewGetPolicyAssignmentOptions(\n", " testPolicyAssignmentId,\n", ")\n", "\n", "policyAssignmentRecord, response, err := iamPolicyManagementService.GetPolicyAssignment(getPolicyAssignmentOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(policyAssignmentRecord, \"\", \" \")\n", "assignmentPolicyID = *policyAssignmentRecord.Resources[0].Policy.ResourceCreated.ID\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetPolicyAssignmentOptions getPolicyAssignmentOptions = new GetPolicyAssignmentOptions.Builder()\n", " .assignmentId(exampleAssignmentId)\n", " .build();\n", "\n", "Response response = service.getPolicyAssignment(getPolicyAssignmentOptions).execute();\n", "PolicyAssignment policyAssignmentRecord = response.getResult();\n", "PolicyAssignmentResources resource = policyAssignmentRecord.getResources().get(0);\n", "PolicyAssignmentResourcePolicy policy = resource.getPolicy();\n", "AssignmentResourceCreated resourceCreated = policy.getResourceCreated();\n", "exampleAssignmentPolicyId = resourceCreated.getId();\n", "\n", "System.out.println(policyAssignmentRecord);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " assignmentId: exampleAssignmentId,\n", "};\n", "\n", "let res;\n", "try {\n", " res = await iamPolicyManagementService.getPolicyAssignment(params);\n", " console.log(JSON.stringify(res.result, null, 2));\n", " exampleAssignmentPolicyId = res.result.resources[0].policy.resource_created.id;\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "response = iam_policy_management_service.get_policy_assignment(\n", " assignment_id=example_assignment_id,\n", ")\n", "policy_assignment_record = response.get_result()\n", "\n", "global example_assignment_policy_id\n", "example_assignment_policy_id = policy_assignment_record['resources'][0]['policy']['resource_created']['id']\n", "\n", "print(json.dumps(policy_assignment_record, indent=2))" ] } ] } ] } } }, "patch": { "tags": [ "Policy assignments" ], "parameters": [ { "name": "version", "in": "query", "description": "specify version of response body format", "required": true, "schema": { "type": "string", "minLength": 1, "enum": [ "1.0" ] } }, { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a policy assignment and must match the Etag value of the existing policy assignment.\nThe Etag can be retrieved using the GET /v1/policy_assignments/{assignment_id} API and looking at the Etag response header.\n", "schema": { "type": "string" } } ], "summary": "Update a policy authorization type assignment", "operationId": "update_policy_assignment", "description": "Update a policy assignment by providing a policy assignment ID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyAssignmentRequest" } } }, "description": "A policy assignment to be created.", "required": true }, "responses": { "200": { "description": "Policy assignment updates successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the policy assignment.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAssignmentV1" }, "examples": { "response": { "value": { "id": "", "account_id": "", "template": { "id": "policyTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "1" }, "target": { "type": "Account", "id": "AccountId" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "Account-1" }, "policy": { "resource_created": { "id": "0000-0000-0000-0001" }, "status": "succeeded" } } ], "href": "https://iam.cloud.ibm.com/v1/policy_assignments/{assignment_id}", "created_at": "2022-07-23T14:09:09.907Z", "created_by_id": "USER_ID", "last_modified_at": "2022-07-23T14:09:09.907Z", "last_modified_by_id": "USER_ID" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested policy assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyAssignmentNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-assignment.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyAssignment.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PATCH \\\n", "'https://iam.cloud.ibm.com/v1/policy_assignments/$POLICY_ASSIGNMENT_ID?version=1.0' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json' \\\n", "-d '{\n", " \"template_version\": \"2\",\n", "}'" ] } ] } ] } } }, "delete": { "x-sdk-exclude": false, "tags": [ "Policy assignments" ], "summary": "Remove a policy assignment", "operationId": "delete_policy_assignment", "description": "Remove a policy template assignment by providing a policy assignment ID. You can't delete a policy assignment if the status is \"in_progress\".\n", "responses": { "204": { "description": "Policy assignment deletion successful." }, "400": { "description": "Policy assignment was not in valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes an assignment with state \"in_progress\", cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to remove the policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested policy assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/PolicyAssignmentNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.policy-assignment.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.policyAssignment.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/policy_assignments/$POLICY_ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/accounts/{account_id}/settings/access_management": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" }, { "name": "account_id", "in": "path", "required": true, "description": "The account GUID that the settings belong to.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9-_]+$" } } ], "get": { "tags": [ "Access Management Settings" ], "summary": "Retrieve Access Management account settings by account ID", "operationId": "get_settings", "description": "Retrieve Access Management settings for an account by providing the account ID.", "responses": { "200": { "description": "Access Management account settings retrieval successful.", "headers": { "ETag": { "schema": { "$ref": "#/components/schemas/IfMatch" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettingsAccessManagement" }, "examples": { "response": { "value": { "external_account_identity_interaction": { "identity_types": { "user": { "state": "monitor", "external_allowed_accounts": [ "100abcde100a41abc100aza678abc0zz", "87654321dcba1a2ba1b20987654321qw" ] }, "service_id": { "state": "enabled", "external_allowed_accounts": [] }, "service": { "state": "monitor", "external_allowed_accounts": [] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the account settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the access management account settings." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.settings.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "\"https://iam.cloud.ibm.com/v1/accounts/$ACCOUNT_ID/settings/access_management\" \\\n", "-H \"Authorization: Bearer $TOKEN\"\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "patch": { "tags": [ "Access Management Settings" ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating Access Management Account Settings and must match the Etag value of the existing Access Management Account Settings.\nThe Etag can be retrieved using the GET /v1/accounts/{account_id}/settings/access_management API and looking at the Etag response header.\n", "schema": { "$ref": "#/components/schemas/IfMatch" } } ], "summary": "Update Access Management account settings by account ID", "operationId": "update_settings", "description": "Update access management settings for an account.\n\n### External Account Identity Interaction\n\nUpdate the way identities within an external account are allowed to interact with the requested account by providing:\n* the `account_id` as a parameter\n* one or more external account ID(s) and state for the specific identity in the request body\n\nExternal account identity interaction includes the following `identity_types`: `user` (user identities that are defined as [IBMid's](https://cloud.ibm.com/docs/account?topic=account-identity-overview#users-bestpract)), `service_id` (defined as [IAM ServiceIds](https://cloud.ibm.com/docs/account?topic=account-identity-overview#serviceid-bestpract)), `service` (defined by a service’s [CRN](https://cloud.ibm.com/docs/account?topic=account-crn)). To update an Identity’s setting, the `state` and `external_allowed_accounts` fields are required.\n\nDifferent identity states are:\n* \"enabled\": An identity type is allowed to access resources in the account provided it has access policies on those resources.\n* \"limited\": An identity type is allowed to access resources in the account provided it has access policies on those resources AND it is associated with either the account the resources are in or one of the allowed accounts. This setting uses the \"external_allowed_accounts\" list.\n* \"monitor\": It has no direct impact on an Identity’s access. Instead, it creates AT events for access decisions as if the account were in a limited “state”.\n\n**Note**: The state \"enabled\" is a special case. In this case, access is given to all accounts and there is no need to specify a particular list. Therefore, when updating \"state\" to \"enabled\" for an identity type \"external_allowed_accounts\" should be left empty.\n", "x-codegen-request-body-name": "settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettingsAccessManagementPatch" } } }, "description": "Access Management Account Settings attribute to be updated.", "required": true }, "responses": { "200": { "description": "Access Management account settings update successful.", "headers": { "ETag": { "schema": { "$ref": "#/components/schemas/IfMatch" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettingsAccessManagement" }, "examples": { "response": { "value": { "external_account_identity_interaction": { "identity_types": { "user": { "state": "monitor", "external_allowed_accounts": [ "100abcde100a41abc100aza678abc0zz", "87654321dcba1a2ba1b20987654321qw" ] }, "service_id": { "state": "monitor", "external_allowed_accounts": [ "100abcde100a41abc100aza678abc0zz" ] }, "service": { "state": "monitor", "external_allowed_accounts": [] } } } } } } } } }, "400": { "description": "Access Management Account settings input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check missing parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the account settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create or update the access management account settings." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ResourceNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.settings.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PATCH \\\n", "\"https://iam.cloud.ibm.com/v1/accounts/$ACCOUNT_ID/settings/access_management\" \\\n", "-H \"Authorization: Bearer $TOKEN\"\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"external_account_identity_interaction\": {\n", " \"identity_types\": {\n", " \"service_id\": {\n", " \"state\": \"monitor\",\n", " \"external_allowed_accounts\": [\"100abcde100a41abc100aza678abc0zz\"]\n", " }\n", " }\n", " }\n", "}'" ] } ] } ] } } } }, "/v1/action_control_templates": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Action Control Templates" ], "summary": "List action control templates by attributes", "operationId": "list_action_control_templates", "description": "List action control templates and filter by attributes by using query parameters.\nThe following attributes are supported:\n`account_id`\n`account_id` is a required query parameter.\nOnly action control templates that have the specified attributes and that\nthe caller has read access to are returned.\nIf the caller does not have read access to any action control templates an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID that the action control templates belong to.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Action Control Templates retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplateCollection" }, "examples": { "response": { "value": { "action_control_templates": [ { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates?account_id=$ACCOUNT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "post": { "tags": [ "Action Control Templates" ], "summary": "Create an action control template", "operationId": "create_action_control_template", "description": "Create an action control template. Action control templates define a service action control.\n", "x-codegen-request-body-name": "action_control_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplatePrototype" } } }, "description": "An action control template to be created.", "required": true }, "responses": { "201": { "description": "Action control template creation is successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplate" }, "examples": { "response": { "value": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "counts": { "template": { "current": 1, "limit": 100 }, "version": { "current": 1, "limit": 100 } }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Action Control template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested action control template." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "An action control template already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "action_control_template_conflict_error", "message": "Failed to create action control template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "actionControlTemplate": "ACTION_CONTROL_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum action control templates quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum action control templates quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"Activity Tracker Event Routing service action control template\",\n", " \"description\": \"Restrict access to updating and deleting ATracker routes\",\n", " \"account_id\": \"ACCOUNT_ID\",\n", " \"action_control\": {\n", " \"description\": \"Restrict access to updating and deleting ATracker routes\",\n", " \"service_name\": \"atracker\",\n", " \"actions\": [\"atracker.route.update\", \"atracker.route.delete\"]\n", " }\n", "}'" ] } ] } ] } } } }, "/v1/action_control_templates/{action_control_template_id}": { "parameters": [ { "name": "action_control_template_id", "in": "path", "required": true, "description": "Action control template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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}$" } } ], "get": { "tags": [ "Action Control Templates" ], "summary": "Retrieve the latest version of an action control template", "operationId": "get_action_control_template", "description": "Retrieve the latest version of an action control template by providing an action control template ID.", "parameters": [ { "name": "state", "in": "query", "description": "The action control template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } } ], "responses": { "200": { "description": "Action control Template retrieval is successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the action control template.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplate" }, "examples": { "response": { "value": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested action control template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID?state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "delete": { "tags": [ "Action Control Templates" ], "summary": "Delete an action control template", "operationId": "delete_action_control_template", "description": "Delete an action control template by providing the action control template ID. This deletes all versions of this template. An action control template can't be deleted if any version of the template is assigned to one or more child accounts. You must remove the action control assignments first.\n", "responses": { "204": { "description": "Action control template deletion is successful." }, "400": { "description": "The action control template was not valid for deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a version that is assigned to an account and cannot proceed with the action." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested action control template version." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/action_control_templates/{action_control_template_id}/versions": { "parameters": [ { "name": "action_control_template_id", "in": "path", "required": true, "description": "The action control template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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}$" } } ], "post": { "tags": [ "Action Control Templates" ], "summary": "Create a new action control template version", "operationId": "create_action_control_template_version", "description": "Create a new version of an action control template. Use this if you need to make updates to an action control template that is committed.\n", "x-codegen-request-body-name": "action_control_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplateVersionPrototype" } } }, "description": "An action control template to be created.", "required": true }, "responses": { "201": { "description": "Action control template creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplate" }, "examples": { "response": { "value": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Action Control template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested action control template." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "An identical action control template already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "action_control_template_conflict_error", "message": "Failed to create action control template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "actionControlTemplate": "ACTION_CONTROL_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum action control templates quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum action control templates quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/action_control_template/$TEMPLATE_ID/versions' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"Activity Tracker Event Routing service action control template\",\n", " \"description\": \"Restrict access to updating and deleting ATracker routes\",\n", " \"action_control\": {\n", " \"description\": \"Restrict access to updating and deleting ATracker routes\",\n", " \"service_name\": \"atracker\",\n", " \"actions\": [\"atracker.route.update\", \"atracker.route.delete\"]\n", " }\n", "}'" ] } ] } ] } } }, "get": { "tags": [ "Action Control Templates" ], "summary": "Retrieve action control template versions", "operationId": "list_action_control_template_versions", "description": "Retrieve the versions of an action control template by providing an action control template ID.", "parameters": [ { "name": "state", "in": "query", "description": "Action control template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Action control template versions retrieval is successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplateVersionsCollection" }, "examples": { "response": { "value": { "versions": [ { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested action control template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID/versions?state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/action_control_templates/{action_control_template_id}/versions/{version}": { "parameters": [ { "name": "action_control_template_id", "in": "path", "required": true, "description": "Action control template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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}$" } }, { "name": "version", "in": "path", "required": true, "description": "Action control template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } ], "put": { "tags": [ "Action Control Templates" ], "summary": "Update an action control template version", "operationId": "replace_action_control_template", "description": "Update a specific version of an action control template. You can use this only if the version isn't committed.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating an action control template version must match the Etag value of the existing action control template version.\nThe Etag can be retrieved using the GET /v1/action_control_templates/{template_id}/versions/{version} API and looking at the Etag response header.\n", "schema": { "type": "string", "minLength": 1 } } ], "x-codegen-request-body-name": "action_control_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplateVersionPrototype" } } }, "description": "Updated action control template content to be saved.", "required": true }, "responses": { "200": { "description": "Action control template version updates successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplate" }, "examples": { "response": { "value": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Action control template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "An action control's service cannot be updated. Create a new action control template and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested action control template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "An identical action control template exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "action_control_template_conflict_error", "message": "Failed to update action control template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "actionControlTemplate": "ACTION_CONTROL_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PUT \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"name\": \"Activity Tracker Event Routing service action control template\",\n", " \"description\": \"Restrict access to updating and deleting ATracker routes\",\n", " \"action_control\": {\n", " \"description\": \"Restrict access to updating and deleting ATracker routes\",\n", " \"service_name\": \"atracker\",\n", " \"actions\": [\"atracker.route.update\", \"atracker.route.delete\"]\n", " }\n", "}'" ] } ] } ] } } }, "delete": { "tags": [ "Action Control Templates" ], "summary": "Delete an action control template version", "operationId": "delete_action_control_template_version", "description": "Delete a specific version of an action control template by providing an action control template ID and version number. You can't delete an action control template version that is assigned to one or more child accounts. You must remove the action control assignments first.\n", "responses": { "204": { "description": "Action control template deletion is successful." }, "400": { "description": "Action control template was not valid for deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a version that is assigned to an account and cannot proceed with the action." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested action control template version." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "get": { "tags": [ "Action Control Templates" ], "summary": "Retrieve an action control template version", "operationId": "get_action_control_template_version", "description": "Retrieve an action control template by providing an action control template ID and version number.", "responses": { "200": { "description": "Action control template retrieval is successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the action control template.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlTemplate" }, "examples": { "response": { "value": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Activity Tracker Event Routing service action control template", "description": "Restrict access to updating and deleting ATracker routes.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "action_control": { "description": "Restrict access to updating and deleting ATracker routes.", "service_name": "atracker", "actions": [ "atracker.route.update", "atracker.route.delete" ] }, "href": "https://iam.cloud.ibm.com/v1/action_control_templates/actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-27T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-27T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested action control template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/action_control_templates/{action_control_template_id}/versions/{version}/commit": { "parameters": [ { "name": "action_control_template_id", "in": "path", "required": true, "description": "Action control template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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}$" } }, { "name": "version", "in": "path", "required": true, "description": "The action control template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } ], "post": { "tags": [ "Action Control Templates" ], "summary": "Commit an action control template version", "operationId": "commit_action_control_template", "description": "Commit an action control template version. You cannot make any further changes to the action control template once it's committed. If you have to make updates after committing a version, create a new version.\n", "x-codegen-request-body-name": "action control", "responses": { "204": { "description": "Action control template version updates successful." }, "400": { "description": "Action control template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "An action control's service cannot be updated. Create a new action control template and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the action control template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested action control template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/action_control_templates/$TEMPLATE_ID/versions/$TEMLPATE_VERSION/commit' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{}'" ] } ] } ] } } } }, "/v1/action_control_assignments": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Action Control Assignments" ], "summary": "Get action control template assignments", "operationId": "list_action_control_assignments", "description": "Get action control template assignments by attributes.\nThe following attributes are supported:\n`account_id`, `template_id`, `template_version`, `sort`.\n`account_id` is a required query parameter.\nOnly action control template assignments with the specified attributes and \naccessible by the caller are returned.\nIf the caller does not have read access to any action control template assignments, an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID in which the action control assignment belongs to.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } }, { "name": "template_id", "in": "query", "description": "Optional template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 51, "pattern": "^actionControlTemplate-[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}$" } }, { "name": "template_version", "in": "query", "description": "Optional action control template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Action control template assignments retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlAssignmentCollection" }, "examples": { "response": { "value": { "assignments": [ { "id": "actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "action_control": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/action_control_assignments/actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-assignment.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlAssignment.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/action_control_assignments?account_id=$ACCOUNT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "post": { "tags": [ "Action Control Assignments" ], "summary": "Create an action control template assignment", "operationId": "create_action_control_template_assignment", "description": "Assign an action control template to child accounts and account groups. This creates the action control in the accounts and account groups that you specify.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlAssignmentPrototype" } } }, "description": "An action control assignment to be created.", "required": true }, "responses": { "201": { "description": "Action control assignment creation is successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlAssignmentCollection" }, "examples": { "response": { "value": { "assignments": [ { "id": "actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "action_control": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/action_control_assignments/actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } ] } } } } } }, "400": { "description": "Action control assignment input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the action control assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested action control assignment." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "An action control assignment exists for the given template ID, version, and target account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "action_control_assignment_conflict_error", "message": "Failed to create action control assignment.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "actionControlAssignment": "ACTION_CONTROL_ASSIGNMENT" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-assignment.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlAssignment.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/action_control_assignments' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"templates\": [{\n", " \"id\": \"template_id\",\n", " \"version\": \"template_version\"\n", " }],\n", " \"target\": {\n", " \"id\": \"target account\",\n", " \"type\": \"target type\"\n", " }\n", "}'" ] } ] } ] } } } }, "/v1/action_control_assignments/{assignment_id}": { "parameters": [ { "name": "assignment_id", "in": "path", "required": true, "description": "Action control template assignment ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } } ], "get": { "tags": [ "Action Control Assignments" ], "summary": "Retrieve an action control assignment", "operationId": "get_action_control_assignment", "description": "Retrieve an action control template assignment by providing an action control assignment ID.", "responses": { "200": { "description": "Action control assignment retrieval is successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the action control assignment.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlAssignment" }, "examples": { "response": { "value": { "id": "actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "action_control": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/action_control_assignments/actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the action control assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested action control assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlAssignmentNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-assignment.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlAssignment.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/action_control_assignments/$ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "patch": { "tags": [ "Action Control Assignments" ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating an action control assignment and must match the Etag value of the existing action control assignment.\nThe Etag can be retrieved using the GET /v1/action_control_assignments/{assignment_id} API and looking at the Etag response header.\n", "schema": { "type": "string" } } ], "summary": "Update an action control assignment", "operationId": "update_action_control_assignment", "description": "Update an action control assignment by providing an action control assignment ID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlAssignmentPatchTemplate" } } }, "description": "An action control assignment to be created.", "required": true }, "responses": { "200": { "description": "Action Control assignment updates successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the action control assignment.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionControlAssignment" }, "examples": { "response": { "value": { "id": "actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "actionControlTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "action_control": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/action_control_assignments/actionControlAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the action control assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested action control assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlAssignmentNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-assignment.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlAssignment.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PATCH \\\n", "'https://iam.cloud.ibm.com/v1/action_control_assignments/$ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json' \\\n", "-d '{\n", " \"template_version\": \"2\",\n", "}'" ] } ] } ] } } }, "delete": { "x-sdk-exclude": false, "tags": [ "Action Control Assignments" ], "summary": "Remove an action control assignment", "operationId": "delete_action_control_assignment", "description": "Remove an action control template assignment by providing an action control assignment ID. You can't delete an action control assignment if the status is \"in_progress\".\n", "responses": { "204": { "description": "Action control assignment deletion successful." }, "400": { "description": "Action control assignment was not in valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes an assignment with state \"in_progress\", cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to remove the action control assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested action control assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlAssignmentNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-assignment.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlAssignment.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/action_control_assignments/$ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/role_templates": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Role Templates" ], "summary": "List role templates by attributes", "operationId": "list_role_templates", "description": "List role templates and filter by attributes by using query parameters.\nThe following attributes are supported:\n`account_id`, `name`, `role_name`, `role_service_name`, `state`, `limit`, `start`.\n`account_id` is a required query parameter.\nOnly role templates that have the specified attributes and that\nthe caller has read access to are returned.\nIf the caller does not have read access to any role templates an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID that the role templates belong to.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } }, { "name": "name", "in": "query", "description": "The role template name.", "schema": { "type": "string", "maxLength": 100, "minLength": 1 } }, { "name": "role_name", "in": "query", "description": "The template role name.", "schema": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[A-Z]{1}[A-Za-z0-9]{0,29}$" } }, { "name": "role_service_name", "in": "query", "description": "The template role service name.", "schema": { "type": "string", "minLength": 1 } }, { "name": "state", "in": "query", "description": "The role template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Role Templates retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplateCollection" }, "examples": { "response": { "value": { "role_templates": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "href": "https://iam.cloud.ibm.com/v1/role_templates/roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-01-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/role_templates?account_id=$ACCOUNT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "post": { "tags": [ "Role Templates" ], "summary": "Create role template", "operationId": "create_role_template", "description": "Create a role template. Role templates define roles from an existing system or service defined role.\n", "x-codegen-request-body-name": "role_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplatePrototype" } } }, "description": "A role template to be created.", "required": true }, "responses": { "201": { "description": "Role template creation is successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplate" }, "examples": { "response": { "value": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "counts": { "template": { "current": 1, "limit": 100 }, "version": { "current": 1, "limit": 100 } }, "href": "https://iam.cloud.ibm.com/v1/role_templates/RoleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Role template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested role template." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A role template already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_template_conflict_error", "message": "Failed to create role template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "roleTemplate": "ROLE_TEMPLATE" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum role templates quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum role templates quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/role_templates' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"Cloud Object Storage Role template\",\n", " \"description\": \"Role templates define roles from an existing system or service defined role\",\n", " \"account_id\": \"ACCOUNT_ID\",\n", " \"role\": {\n", " \"name\": \"CosCreateBucket\",\n", " \"display_name\": \"COS Bucket Create\",\n", " \"description\": \"Role templates define roles from an existing system or service defined role\",\n", " \"service_name\": \"cloud-object-storage\",\n", " \"actions\": [\"ACTION_ID_1\", \"ACTION_ID_2\"]\n", " }\n", "}'" ] } ] } ] } } } }, "/v1/role_templates/{role_template_id}": { "parameters": [ { "name": "role_template_id", "in": "path", "required": true, "description": "Role template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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}$" } } ], "get": { "tags": [ "Role Templates" ], "summary": "Retrieve the latest version of a role template", "operationId": "get_role_template", "description": "Retrieve the latest version of a role template by providing a role template ID.", "parameters": [ { "name": "state", "in": "query", "description": "The role template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } } ], "responses": { "200": { "description": "Role Template retrieval is successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the role template.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplate" }, "examples": { "response": { "value": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "href": "https://iam.cloud.ibm.com/v1/role_templates/roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested role template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID&state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "delete": { "tags": [ "Role Templates" ], "summary": "Delete a Role template", "operationId": "delete_role_template", "description": "Delete a role template by providing the role template ID. This deletes all versions of this template. A role template can't be deleted if any version of the template is assigned to one or more child accounts. You must remove the role assignments first.\n", "responses": { "204": { "description": "Role template deletion is successful." }, "400": { "description": "The role template was not valid for deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a version that is assigned to an account and cannot proceed with the action." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested role template version." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleTemplateNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/role_templates/{role_template_id}/versions": { "parameters": [ { "name": "role_template_id", "in": "path", "required": true, "description": "The role template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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}$" } } ], "post": { "tags": [ "Role Templates" ], "summary": "Create a new role template version", "operationId": "create_role_template_version", "description": "Create a new version of a role template. Use this if you need to make updates to a role template that is committed.\n", "x-codegen-request-body-name": "role_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplateVersionPrototype" } } }, "description": "A role template to be created.", "required": true }, "responses": { "201": { "description": "Role template creation successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplate" }, "examples": { "response": { "value": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "href": "https://iam.cloud.ibm.com/v1/role_templates/roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Role template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested role template." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "An identical role template already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_template_conflict_error", "message": "Failed to create role template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "RoleTemplate": "ROLE_TEMPLATE" } } } ], "status_code": 409 } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "Exceeded maximum role templates quota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "request_not_processed", "message": "Exceeded maximum role templates quota () for account ." } ], "status_code": 422 } } } } } }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/role_template/$TEMPLATE_ID/versions' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"name\": \"Resource Access\",\n", " \"description\": \"Restrict access to billing discount reports\",\n", " \"role\": {\n", " \"description\": \"COS Bucket Creator\",\n", " \"display_name\": \"COS Bucket Creator\",\n", " \"service_name\": \"cloud-object-storage\",\n", " \"actions\": [\"cloud-object-storage.bucket.put_bucket\", \"ACTION_ID_2\"]\n", " }\n", "}'" ] } ] } ] } } }, "get": { "tags": [ "Role Templates" ], "summary": "Retrieve role template versions", "operationId": "list_role_template_versions", "description": "Retrieve the versions of a role template by providing a role template ID.", "parameters": [ { "name": "state", "in": "query", "description": "Role template state.", "schema": { "type": "string", "enum": [ "active", "deleted" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "Role template versions retrieval is successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplateVersionsCollection" }, "examples": { "response": { "value": { "versions": [ { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "href": "https://iam.cloud.ibm.com/v1/role_templates/roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested role template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID/versions&state=active' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/role_templates/{role_template_id}/versions/{version}": { "parameters": [ { "name": "role_template_id", "in": "path", "required": true, "description": "Role template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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}$" } }, { "name": "version", "in": "path", "required": true, "description": "Role template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } ], "put": { "tags": [ "Role Templates" ], "summary": "Update a role template version", "operationId": "replace_role_template", "description": "Update a specific version of a role template. You can use this only if the version isn't committed.\n", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a role template version must match the Etag value of the existing role template version.\nThe Etag can be retrieved using the GET /v1/role_templates/{template_id}/versions/{version} API and looking at the Etag response header.\n", "schema": { "type": "string", "minLength": 1 } } ], "x-codegen-request-body-name": "role_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplateVersionPrototype" } } }, "description": "Updated role template content to be saved.", "required": true }, "responses": { "200": { "description": "Role template version updates successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplate" }, "examples": { "response": { "value": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "href": "https://iam.cloud.ibm.com/v1/role_templates/roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "400": { "description": "Role template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Role's service cannot be updated. Create a new role template and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested role template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "An identical role template exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_template_conflict_error", "message": "Failed to update role template.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "roleTemplate": "Role_TEMPLATE" } } } ], "status_code": 409 } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PUT \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-H 'If-Match: $ETAG'\\\n", "-d '{\n", " \"name\": \"COS bucket access\",\n", " \"description\": \"COS Meta reader role for use case X.\",\n", " \"role\": {\n", " \"display_name\": \"COS Bucket Creator.\",\n", " \"description\": \"COS Meta reader role for use case X.\",\n", " \"service_name\": \"cloud-object-storage\",\n", " \"actions\": [\"cloud-object-storage.bucket.put_bucket\", \"ACTION_ID_2\"]\n", " }\n", "}'" ] } ] } ] } } }, "delete": { "tags": [ "Role Templates" ], "summary": "Delete a role template version", "operationId": "delete_role_template_version", "description": "Delete a specific version of a role template by providing a role template ID and version number. You can't delete a role template version that is assigned to one or more child accounts. You must remove the role assignments first.\n", "responses": { "204": { "description": "Role template deletion is successful." }, "400": { "description": "Role template was not valid for deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes a version that is assigned to an account and cannot proceed with the action." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to delete the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested role template version." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleTemplateNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "get": { "tags": [ "Role Templates" ], "summary": "Retrieve a role template version", "operationId": "get_role_template_version", "description": "Retrieve a role template by providing a role template ID and version number.", "responses": { "200": { "description": "Role template retrieval is successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the role template.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleTemplate" }, "examples": { "response": { "value": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "name": "Cloud Object Storage Role template", "description": "Allow action to create a bucket in Cloud Object Storage.", "version": "1", "account_id": "0000-0000-0000-0001", "committed": true, "role": { "name": "CosBucketCreator", "display_name": "COS Bucket Creator", "description": "Allow action to create a bucket in Cloud Object Storage.", "service_name": "cloud-object-storage", "actions": [ "cloud-object-storage.bucket.put_bucket" ] }, "href": "https://iam.cloud.ibm.com/v1/role_templates/roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "created_at": "2025-09-15T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-09-15T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678", "state": "active" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested role template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/ActionControlTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.action-control-template.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.actionControlTemplate.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID/versions/$TEMPLATE_VERSION' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } }, "/v1/role_templates/{role_template_id}/versions/{version}/commit": { "parameters": [ { "name": "role_template_id", "in": "path", "required": true, "description": "Role template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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}$" } }, { "name": "version", "in": "path", "required": true, "description": "The role template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } ], "post": { "tags": [ "Role Templates" ], "summary": "Commit a role template version", "operationId": "commit_role_template", "description": "Commit a role template version. You cannot make any further changes to the role template once it's committed. If you have to make updates after committing a version, create a new version.\n", "x-codegen-request-body-name": "role template", "responses": { "204": { "description": "Role template version updates successful." }, "400": { "description": "Role template input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Role's service cannot be updated. Create a new role template and delete the existing one." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to update the role template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to update the requested role template." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleTemplateNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-template.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleTemplate.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/role_templates/$TEMPLATE_ID/versions/$TEMLPATE_VERSION/commit' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{}'" ] } ] } ] } } } }, "/v1/role_assignments": { "parameters": [ { "$ref": "#/components/parameters/acceptLanguage" } ], "get": { "tags": [ "Role Assignments" ], "summary": "Get role template assignments", "operationId": "list_role_assignments", "description": "Get role template assignments by attributes.\nThe following attributes are supported:\n`account_id`, `template_id`, `template_version`, `target`, `target_type`, `limit`, `start`.\n`account_id` is a required query parameter.\nOnly role template assignments with the specified attributes and \naccessible by the caller are returned.\nIf the caller does not have read access to any role template assignments, an empty array\nis returned.\n", "parameters": [ { "name": "account_id", "in": "query", "required": true, "description": "The account GUID in which the role assignment belongs to.", "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } }, { "name": "template_id", "in": "query", "description": "Optional template ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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}$" } }, { "name": "template_version", "in": "query", "description": "Optional role template version.", "schema": { "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/start" } ], "responses": { "200": { "description": "role template assignments retrieval successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignmentCollection" }, "examples": { "response": { "value": { "assignments": [ { "id": "roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "role": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/role_assignments/roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } ] } } } } } }, "400": { "description": "The request you made is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "missing_required_query_parameter", "message": "'account_id' is a required query parameter" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-assignment.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleAssignment.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/role_assignments?account_id=$ACCOUNT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "post": { "tags": [ "Role Assignments" ], "summary": "Create a role template assignment", "operationId": "create_role_template_assignment", "description": "Assign a role template to child accounts and account groups. This creates the role in the accounts and account groups that you specify.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignmentPrototype" } } }, "description": "An role assignment to be created.", "required": true }, "responses": { "201": { "description": "Role assignment creation is successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignmentCollection" }, "examples": { "response": { "value": { "assignments": [ { "id": "roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "role": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/role_assignments/roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } ] } } } } } }, "400": { "description": "Role assignment input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Invalid body format. Check the input parameters." } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to create the role assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to create the requested role assignment." } ], "status_code": 403 } } } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "409": { "description": "A role assignment exists for the given template ID, version, and target account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_assignment_conflict_error", "message": "Failed to create role assignment.", "details": { "conflicts_with": { "etag": "1-847833cec3bf3f3c3231d8f9492febac", "roleAssignment": "ACTION_CONTROL_ASSIGNMENT" } }, "status_code": 409 } ] } } } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-assignment.create" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleAssignment.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST \\\n", "'https://iam.cloud.ibm.com/v1/role_assignments' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'\\\n", "-d '{\n", " \"templates\": [{\n", " \"id\": \"template_id\",\n", " \"version\": \"template_version\"\n", " }],\n", " \"target\": {\n", " \"id\": \"target account\",\n", " \"type\": \"target type\"\n", " }\n", "}'" ] } ] } ] } } } }, "/v1/role_assignments/{assignment_id}": { "parameters": [ { "name": "assignment_id", "in": "path", "required": true, "description": "Role template assignment ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } } ], "get": { "tags": [ "Role Assignments" ], "summary": "Retrieve a role assignment", "operationId": "get_role_assignment", "description": "Retrieve a role template assignment by providing a role assignment ID.", "responses": { "200": { "description": "Role assignment retrieval is successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the role assignment.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" }, "examples": { "response": { "value": { "id": "roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "role": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/role_assignments/roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the role assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested role assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleAssignmentNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-assignment.read" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleAssignment.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET \\\n", "'https://iam.cloud.ibm.com/v1/role_assignments/$ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } }, "patch": { "tags": [ "Role Assignments" ], "parameters": [ { "name": "If-Match", "in": "header", "required": true, "description": "The revision number for updating a role assignment and must match the Etag value of the existing role assignment.\nThe Etag can be retrieved using the GET /v1/role_assignments/{assignment_id} API and looking at the Etag response header.\n", "schema": { "type": "string" } } ], "summary": "Update a role assignment", "operationId": "update_role_assignment", "description": "Update a role assignment by providing a role assignment ID.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignmentPatchTemplate" } } }, "description": "A role assignment to be created.", "required": true }, "responses": { "200": { "description": "Role assignment updates successful.", "headers": { "ETag": { "schema": { "description": "The revision number of the role assignment.", "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleAssignment" }, "examples": { "response": { "value": { "id": "roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "account_id": "0000-0000-0000-0001", "template": { "id": "roleTemplate-12345678-abcd-1a2b-a1b2-1234567890ab", "version": "2" }, "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "status": "succeeded", "resources": [ { "target": { "type": "Account", "id": "0000-0000-0000-0002" }, "role": { "resource_created": { "id": "1001-1001-0000-0002" } } } ], "href": "https://iam.cloud.ibm.com/v1/role_assignments/roleAssignment-87654321-dcba-b2a1-a1b2-ba0987654321", "created_at": "2025-01-29T14:09:09.907Z", "created_by_id": "IBMid-12345678", "last_modified_at": "2025-01-29T14:09:09.907Z", "last_modified_by_id": "IBMid-12345678" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to retrieve the role assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to retrieve the requested role assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleAssignmentNotFound" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-assignment.update" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleAssignment.update" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X PATCH \\\n", "'https://iam.cloud.ibm.com/v1/role_assignments/$ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json' \\\n", "-d '{\n", " \"template_version\": \"2\",\n", "}'" ] } ] } ] } } }, "delete": { "x-sdk-exclude": false, "tags": [ "Role Assignments" ], "summary": "Remove a role assignment", "operationId": "delete_role_assignment", "description": "Remove a role template assignment by providing a role assignment ID. You can't delete a role assignment if the status is \"in_progress\".\n", "responses": { "204": { "description": "Role assignment deletion successful." }, "400": { "description": "Role assignment was not in valid to delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_body", "message": "Request includes an assignment with state \"in_progress\", cannot perform action" } ], "status_code": 400 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "You do not have access to remove the role assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "insufficent_permissions", "message": "You are not allowed to delete the requested role assignment." } ], "status_code": 403 } } } } } }, "404": { "$ref": "#/components/responses/RoleAssignmentNotFound" }, "429": { "$ref": "#/components/responses/RateLimit" } }, "x-ibm-release-level": "beta", "x-ibm-permissions": { "actions": [ { "name": "iam-access-management.role-assignment.delete" } ] }, "x-ibm-events": { "events": [ { "name": "iam-am.roleAssignment.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE \\\n", "'https://iam.cloud.ibm.com/v1/role_assignments/$ASSIGNMENT_ID' \\\n", "-H 'Authorization: Bearer $TOKEN'\\\n", "-H 'Content-Type: application/json'" ] } ] } ] } } } } }, "components": { "parameters": { "acceptLanguage": { "name": "Accept-Language", "in": "header", "required": false, "description": "Language code for translations\n* `default` - English\n* `de` - German (Standard)\n* `en` - English\n* `es` - Spanish (Spain)\n* `fr` - French (Standard)\n* `it` - Italian (Standard)\n* `ja` - Japanese\n* `ko` - Korean\n* `pt-br` - Portuguese (Brazil)\n* `zh-cn` - Chinese (Simplified, PRC)\n* `zh-tw` - (Chinese, Taiwan)", "schema": { "type": "string", "default": "default", "minLength": 1 } }, "limit": { "name": "limit", "in": "query", "required": false, "description": "The number of documents to include in the collection.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, "start": { "name": "start", "in": "query", "required": false, "description": "Page token that refers to the page of the collection to return.", "schema": { "type": "string", "minLength": 9, "maxLength": 100, "pattern": "^[-A-Za-z0-9+/]*$" } } }, "responses": { "Unauthorized": { "description": "The token that you provided is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "invalid_token", "message": "The provided IAM token is invalid." } ], "status_code": 401 } } } } } }, "PolicyNotFound": { "description": "The policy was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 } } } } } }, "RoleNotFound": { "description": "Role was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_not_found", "message": "Role with ID ROLE_ID not found." } ], "status_code": 404 } } } } } }, "NotFound": { "description": "Resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "not_found", "message": "Not Found" } ], "status_code": 404 } } } } } }, "NotAcceptable": { "description": "The requested resource(s) cannot be formatted that uses the requested media type(s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "unable_to_process", "message": "The requested resource(s) can be formatted that only uses the 'application/json' media type." } ], "status_code": 406 } } } } } }, "UnsupportedMediaType": { "description": "The request body sent was formatted that uses an unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "unsupported_content_type", "message": "The supported media type for this API is 'application/json'." } ], "status_code": 415 } } } } } }, "RateLimit": { "description": "Too many requests are within a time window.", "headers": { "Retry-After": { "description": "The response providing header details about when to the send next request.", "schema": { "description": "The time in seconds to wait before sending the next request.", "type": "integer", "minimum": 1, "maximum": 999999 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "too_many_requests", "message": "Too many requests." } ], "status_code": 429 } } } } } }, "PolicyTemplateNotFound": { "description": "A policy Template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_template_not_found", "message": "Policy with Id POLICY_ID not found." } ], "status_code": 404 } } } } } }, "PolicyAssignmentNotFound": { "description": "Policy Template Assignment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "policy_assignment_not_found", "message": "Policy assignment with ID POLICY_ASSIGNMENT_ID not found." } ], "status_code": 404 } } } } } }, "ResourceNotFound": { "description": "Resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "resource_not_found", "message": "account_id 100abcde100a41a?c100aza678abc0&z is malformed." } ], "status_code": 404 } } } } } }, "ActionControlTemplateNotFound": { "description": "Action control template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "action_control_template_not_found", "message": "An action control with ID ACTION_CONTROL_ID not found." } ], "status_code": 404 } } } } } }, "ActionControlAssignmentNotFound": { "description": "Action control template assignment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "action_control_assignment_not_found", "message": "An action control assignment with Id ACTION_CONTROL_ASSIGNMENT_ID not found." } ], "status_code": 404 } } } } } }, "RoleTemplateNotFound": { "description": "Role template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_template_not_found", "message": "A role with ID ROLE_ID not found." } ], "status_code": 404 } } } } } }, "RoleAssignmentNotFound": { "description": "Role template assignment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "trace": "26f0b2491ed6425c9e7b0c08a3a645f7", "errors": [ { "code": "role_assignment_not_found", "message": "A Role assignment with Id ROLE_ASSIGNMENT_ID not found." } ], "status_code": 404 } } } } } } }, "securitySchemes": { "IAM": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "IAM token." } }, "schemas": { "IfMatch": { "description": "The revision identifier of a document.", "maxLength": 43, "minLength": 5, "pattern": "^[1-9]\\d{0,9}-[\\da-f]{32}|0-new$", "type": "string" }, "Limit": { "description": "The number of documents to include per each page of the collection.", "type": "integer", "minimum": 1, "maximum": 100 }, "Start": { "description": "Page token that refers to the page of the collection.", "type": "string", "minLength": 9, "maxLength": 100, "pattern": "^[-A-Za-z0-9+/]*$" }, "Href": { "description": "The href linking to the page of requested collection.", "type": "string", "readOnly": true }, "First": { "description": "Details with linking href to first page of requested collection.", "type": "object", "properties": { "href": { "$ref": "#/components/schemas/Href" } } }, "Next": { "description": "Details with href linking to the following page of requested collection.", "type": "object", "properties": { "href": { "$ref": "#/components/schemas/Href" }, "start": { "$ref": "#/components/schemas/Start" } } }, "Previous": { "description": "Details with linking href to previous page of requested collection.", "type": "object", "properties": { "href": { "$ref": "#/components/schemas/Href" }, "start": { "$ref": "#/components/schemas/Start" } } }, "PolicyRole": { "description": "A role associated with a policy.", "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "string", "description": "The role Cloud Resource Name (CRN) granted by the policy.\nExample CRN: 'crn:v1:bluemix:public:iam::::role:Editor'" }, "display_name": { "description": "The display name of the role.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 50, "pattern": "^((?!<|>).)*$" }, "description": { "description": "The description of the role.", "type": "string", "readOnly": true, "maxLength": 250 } } }, "SubjectAttribute": { "description": "An attribute associated with a subject.", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The name of an attribute." }, "value": { "type": "string", "description": "The value of an attribute." } } }, "PolicySubject": { "description": "The subject attribute values that must match in order for this policy to apply in a permission decision.", "type": "object", "required": [ "attributes" ], "properties": { "attributes": { "type": "array", "description": "List of subject attributes.", "minItems": 1, "items": { "$ref": "#/components/schemas/SubjectAttribute" } } } }, "ResourceAttribute": { "description": "An attribute associated with a resource.", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The name of an attribute." }, "value": { "type": "string", "description": "The value of an attribute.", "minLength": 1, "maxLength": 1000 }, "operator": { "type": "string", "description": "The operator of an attribute.", "minLength": 1 } } }, "ResourceTag": { "description": "A tag associated with a resource.", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The name of an access management tag.", "pattern": "^[a-zA-Z0-9 _.-]*$", "minLength": 1, "maxLength": 128 }, "value": { "type": "string", "description": "The value of an access management tag.", "pattern": "^[a-zA-Z0-9 _*?.-]*$", "minLength": 1, "maxLength": 1000 }, "operator": { "type": "string", "description": "The operator of an access management tag.", "minLength": 1 } } }, "PolicyResource": { "description": "The attributes of the resource.\nNote that only one resource is allowed in a policy.\n", "type": "object", "required": [ "attributes" ], "properties": { "attributes": { "type": "array", "description": "List of resource attributes.", "minItems": 1, "items": { "$ref": "#/components/schemas/ResourceAttribute" } }, "tags": { "type": "array", "description": "List of access management tags.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/ResourceTag" } } } }, "PolicyBase": { "description": "The core set of properties associated with a policy.", "type": "object", "required": [ "type", "subjects", "roles", "resources" ], "properties": { "type": { "type": "string", "description": "The policy type; either 'access' or 'authorization'.", "minLength": 6, "maxLength": 13, "pattern": "^[a-z]+$" }, "description": { "type": "string", "description": "Customer-defined description", "minLength": 1, "maxLength": 300 }, "subjects": { "description": "The subjects associated with a policy.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/PolicySubject" } }, "roles": { "description": "A set of role Cloud Resource Names (CRNs) granted by the policy.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/PolicyRole" } }, "resources": { "description": "The resources associated with a policy.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/PolicyResource" } } } }, "PolicyRequest": { "allOf": [ { "$ref": "#/components/schemas/PolicyBase" } ] }, "TemplateMetadata": { "description": "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.", "type": "object", "properties": { "id": { "description": "The policy template ID.", "type": "string", "minLength": 1, "maxLength": 51 }, "version": { "description": "Template version.", "type": "string", "minLength": 1, "maxLength": 2 }, "assignment_id": { "description": "Policy assignment ID.", "type": "string", "minLength": 1, "maxLength": 53 }, "root_id": { "description": "Orchestrator template ID.", "type": "string", "minLength": 1 }, "root_version": { "description": "Orchestrator template version.", "type": "string", "minLength": 1 } } }, "Policy": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "The policy ID.", "readOnly": true } } }, { "$ref": "#/components/schemas/PolicyBase" }, { "type": "object", "properties": { "href": { "description": "The href links back to the policy.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the policy was created.", "type": "string", "format": "date-time", "readOnly": true }, "created_by_id": { "description": "The IAM ID of the entity that created the policy.", "type": "string", "readOnly": true }, "last_modified_at": { "description": "The UTC timestamp when the policy was last modified.", "type": "string", "format": "date-time", "readOnly": true }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the policy.", "type": "string", "readOnly": true }, "state": { "description": "The policy state.", "type": "string", "enum": [ "active", "deleted" ] } } } ] }, "PolicyTemplateMetaData": { "allOf": [ { "$ref": "#/components/schemas/Policy" }, { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/TemplateMetadata" } } } ] }, "PolicyCollection": { "description": "A collection of policies.", "type": "object", "required": [ "policies" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "policies": { "type": "array", "description": "List of policies.", "items": { "$ref": "#/components/schemas/PolicyTemplateMetaData" } } } }, "Role": { "description": "A role resource.", "type": "object", "required": [ "display_name", "actions" ], "properties": { "display_name": { "type": "string", "description": "The display the name of the role that is shown in the console.", "minLength": 1, "maxLength": 50 }, "description": { "description": "The description of the role.", "type": "string", "minLength": 1, "maxLength": 250 }, "actions": { "type": "array", "description": "The actions of the role. For more information, see [IAM roles and actions](https://cloud.ibm.com/docs/account?topic=account-iam-service-roles-actions).", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "description": "The action ID.", "minLength": 1 } }, "crn": { "type": "string", "description": "The role Cloud Resource Name (CRN).\nExample CRN: 'crn:v1:ibmcloud:public:iam-access-management::a/exampleAccountId::customRole:ExampleRoleName'", "readOnly": true } } }, "RoleExtra": { "description": "An additional set of properties associated with a role.", "type": "object", "required": [ "name", "account_id", "service_name" ], "properties": { "name": { "type": "string", "description": "The name of the role that is used in the CRN. This must be alphanumeric and capitalized.", "minLength": 1, "maxLength": 30, "pattern": "^[A-Z]{1}[A-Za-z0-9]{0,29}$", "example": "Developer" }, "account_id": { "type": "string", "description": "The account GUID." }, "service_name": { "type": "string", "description": "The service name.", "example": "iam-groups" } } }, "RolePostRequest": { "description": "A role resource to be created.", "allOf": [ { "$ref": "#/components/schemas/Role" }, { "$ref": "#/components/schemas/RoleExtra" }, { "type": "object" } ] }, "CustomRole": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "The role ID. Composed of hexadecimal characters.", "readOnly": true } } }, { "$ref": "#/components/schemas/Role" }, { "$ref": "#/components/schemas/RoleExtra" }, { "type": "object", "properties": { "created_at": { "description": "The UTC timestamp when the role was created.", "type": "string", "format": "date-time", "readOnly": true }, "created_by_id": { "description": "The IAM ID of the entity that created the role.", "type": "string", "readOnly": true }, "last_modified_at": { "description": "The UTC timestamp when the role was last modified.", "type": "string", "format": "date-time", "readOnly": true }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the policy.", "type": "string", "readOnly": true }, "href": { "description": "The href links back to the role.", "type": "string", "readOnly": true } } } ] }, "RoleCollection": { "description": "A collection of roles returned by the 'list roles' operation.", "type": "object", "required": [ "custom_roles", "service_roles", "system_roles" ], "properties": { "custom_roles": { "type": "array", "description": "List of custom roles.", "items": { "$ref": "#/components/schemas/CustomRole" } }, "service_roles": { "type": "array", "description": "List of service roles.", "items": { "$ref": "#/components/schemas/Role" } }, "system_roles": { "type": "array", "description": "List of system roles.", "items": { "$ref": "#/components/schemas/Role" } } } }, "PatchPolicyRequest": { "description": "Policy attributes to be updated.", "type": "object", "properties": { "state": { "$ref": "#/components/schemas/State" } } }, "State": { "description": "The policy state.", "type": "string", "enum": [ "active", "deleted" ] }, "ConflictsWith": { "description": "Details of conflicting resource.", "type": "object", "properties": { "etag": { "description": "The revision number of the resource", "type": "string" }, "role": { "description": "The conflicting role of ID.", "type": "string" }, "policy": { "description": "The conflicting policy ID.", "type": "string" } } }, "ErrorDetails": { "description": "Additional error details.", "type": "object", "properties": { "conflicts_with": { "$ref": "#/components/schemas/ConflictsWith" } } }, "ErrorObject": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "description": "The API error code for the error.", "type": "string", "enum": [ "insufficent_permissions", "invalid_body", "invalid_token", "missing_required_query_parameter", "not_found", "policy_conflict_error", "policy_not_found", "request_not_processed", "role_conflict_error", "role_not_found", "too_many_requests", "unable_to_process", "unsupported_content_type", "policy_template_conflict_error", "policy_template_not_found", "policy_assignment_not_found", "policy_assignment_conflict_error", "resource_not_found", "action_control_template_not_found", "action_control_assignment_not_found", "role_template_conflict_error", "role_template_not_found", "role_assignment_not_found" ] }, "message": { "description": "The error message returned by the API.", "type": "string" }, "details": { "$ref": "#/components/schemas/ErrorDetails" }, "more_info": { "description": "Additional info for error.", "type": "string" } } }, "ErrorResponse": { "description": "The error response from API.", "type": "object", "required": [ "trace", "errors", "status_code" ], "properties": { "trace": { "description": "The unique transaction ID for the request.", "type": "string" }, "errors": { "description": "The errors encountered during the response.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/ErrorObject" } }, "status_code": { "description": "The HTTP error code of the response.", "type": "integer", "minimum": 0, "maximum": 600 } } }, "AttributeValue": { "description": "The value of a rule, resource, or subject attribute; can be boolean or string for resource and subject attribute.\nCan be a string or an array of strings (for example, an array of days to permit access) for rule attribute." }, "V2PolicySubjectAttribute": { "description": "Subject attribute for whom the policy grants access.", "type": "object", "required": [ "key", "operator", "value" ], "properties": { "key": { "type": "string", "description": "The name of a subject attribute. For example, iam_id, access_group_id.", "minLength": 1, "pattern": "^[a-zA-Z0-9_]*$" }, "operator": { "type": "string", "description": "The operator of an attribute.", "minLength": 1, "enum": [ "stringEquals", "stringExists" ] }, "value": { "$ref": "#/components/schemas/AttributeValue" } } }, "V2PolicyResourceAttribute": { "description": "Resource attribute to which the policy grants access.", "type": "object", "required": [ "key", "operator", "value" ], "properties": { "key": { "type": "string", "description": "The name of a resource attribute.", "minLength": 1, "pattern": "^[a-zA-Z0-9_]*$" }, "operator": { "type": "string", "description": "The operator of an attribute.", "minLength": 1, "enum": [ "stringEquals", "stringExists", "stringMatch", "stringEqualsAnyOf", "stringMatchAnyOf" ] }, "value": { "$ref": "#/components/schemas/AttributeValue" } } }, "RuleAttribute": { "description": "Rule that specifies additional access that is granted (For example, time-based condition).", "type": "object", "required": [ "key", "operator", "value" ], "properties": { "key": { "type": "string", "description": "The name of an attribute.", "minLength": 1 }, "operator": { "type": "string", "description": "The operator of an attribute.", "minLength": 1, "enum": [ "stringEquals", "stringExists", "stringEqualsAnyOf", "stringMatchAnyOf", "stringMatch", "timeLessThan", "timeLessThanOrEquals", "timeGreaterThan", "timeGreaterThanOrEquals", "dateLessThan", "dateLessThanOrEquals", "dateGreaterThan", "dateGreaterThanOrEquals", "dateTimeLessThan", "dateTimeLessThanOrEquals", "dateTimeGreaterThan", "dateTimeGreaterThanOrEquals", "dayOfWeekEquals", "dayOfWeekAnyOf" ] }, "value": { "$ref": "#/components/schemas/AttributeValue" } } }, "V2PolicyResourceTag": { "description": "A tag associated with a resource.", "type": "object", "required": [ "key", "value", "operator" ], "properties": { "key": { "type": "string", "description": "The name of an access management tag.", "pattern": "^[a-zA-Z0-9 _.-]*$", "minLength": 1, "maxLength": 128 }, "value": { "type": "string", "description": "The value of an access management tag.", "pattern": "^[a-zA-Z0-9 _*?.-]*$", "minLength": 1, "maxLength": 1000 }, "operator": { "type": "string", "description": "The operator of an access management tag.", "minLength": 1, "enum": [ "stringEquals", "stringMatch" ] } } }, "RuleWithConditions": { "description": "Rule that specifies additional access that is granted (for example, time-based condition) accross multiple conditions.", "type": "object", "required": [ "operator", "conditions" ], "properties": { "operator": { "description": "Operator to evaluate conditions.", "type": "string", "enum": [ "and", "or" ] }, "conditions": { "description": "List of conditions associated with a policy. For example, time-based conditions that grant access over a certain time period.", "minItems": 2, "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/RuleAttribute" } } } }, "NestedCondition": { "description": "Condition that specifies additional conditions or RuleAttribute to grant access.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RuleAttribute" }, { "$ref": "#/components/schemas/RuleWithConditions" } ] }, "RuleWithNestedConditions": { "description": "Rule that specifies additional access that is granted (for example, time-based condition) accross multiple conditions.", "type": "object", "required": [ "operator", "conditions" ], "properties": { "operator": { "description": "Operator to evaluate conditions.", "type": "string", "enum": [ "and", "or" ] }, "conditions": { "description": "List of conditions associated with a policy. For example, time-based conditions that grant access over a certain time period.", "minItems": 2, "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/NestedCondition" } } } }, "V2PolicySubject": { "description": "The subject attributes for whom the policy grants access.", "type": "object", "required": [ "attributes" ], "properties": { "attributes": { "description": "List of subject attributes associated with policy.", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/V2PolicySubjectAttribute" } } } }, "Control": { "description": "Specifies the type of access that is granted by the policy.", "type": "object", "required": [ "grant" ], "properties": { "grant": { "$ref": "#/components/schemas/Grant" } } }, "Grant": { "description": "Permission is granted by the policy.", "type": "object", "required": [ "roles" ], "properties": { "roles": { "description": "A set of role Cloud Resource Names (CRNs) granted by the policy.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Roles" } } } }, "Roles": { "description": "A role associated with a policy.", "type": "object", "required": [ "role_id" ], "properties": { "role_id": { "type": "string", "description": "The role Cloud Resource Name (CRN) granted by the policy.\nExample CRN: 'crn:v1:bluemix:public:iam::::role:Editor'" } } }, "ControlResponse": { "oneOf": [ { "$ref": "#/components/schemas/Control" }, { "$ref": "#/components/schemas/ControlWithEnrichedRoles" } ] }, "ControlWithEnrichedRoles": { "description": "Specifies the type of access that is granted by the policy with additional role information.", "type": "object", "required": [ "grant" ], "properties": { "grant": { "$ref": "#/components/schemas/GrantWithEnrichedRoles" } } }, "GrantWithEnrichedRoles": { "description": "Permission granted by the policy with translated roles and additional role information.", "type": "object", "required": [ "roles" ], "properties": { "roles": { "description": "A set of roles granted by the policy.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/EnrichedRoles" } } } }, "EnrichedRoles": { "type": "object", "description": "A role associated with a policy with additional information (display_name, description, actions) when `format=display`.", "required": [ "role_id", "display_name", "description", "actions" ], "properties": { "role_id": { "type": "string", "description": "The role Cloud Resource Name (CRN) granted by the policy.\nExample CRN: 'crn:v1:bluemix:public:iam::::role:Editor'" }, "display_name": { "description": "The display name of the role, either service-defined or user-defined for custom roles.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 50 }, "description": { "description": "The role description, either service-defined or user-defined for custom roles.", "type": "string", "readOnly": true, "maxLength": 250 }, "actions": { "type": "array", "description": "The actions of the role. For more information, see [IAM roles and actions](https://cloud.ibm.com/docs/account?topic=account-iam-service-roles-actions).", "minItems": 1, "items": { "$ref": "#/components/schemas/RoleAction" } } } }, "RoleAction": { "description": "An action that can be performed by the policy subject when assigned a role.", "type": "object", "required": [ "id", "display_name", "description" ], "properties": { "id": { "description": "Unique identifier for action with structure service.resource.action. For example, cbr.rule.read.", "type": "string" }, "display_name": { "description": "Services defined display name for action.", "type": "string" }, "description": { "description": "Service defined description for action.", "type": "string" } } }, "V2PolicyResource": { "description": "The resource attributes to which the policy grants access.", "type": "object", "required": [ "attributes" ], "properties": { "attributes": { "description": "List of resource attributes to which the policy grants access.", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/V2PolicyResourceAttribute" } }, "tags": { "description": "Optional list of resource tags to which the policy grants access.", "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/components/schemas/V2PolicyResourceTag" } } } }, "V2PolicyRule": { "description": "Additional access conditions associated with the policy.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RuleAttribute" }, { "$ref": "#/components/schemas/RuleWithNestedConditions" } ] }, "V2PolicyBase": { "description": "The core set of properties associated with the policy.", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The policy type; either 'access' or 'authorization'.", "enum": [ "access", "authorization" ] }, "description": { "type": "string", "description": "Description of the policy.", "pattern": "^.*$", "minLength": 1, "maxLength": 300 }, "subject": { "$ref": "#/components/schemas/V2PolicySubject" }, "resource": { "$ref": "#/components/schemas/V2PolicyResource" }, "pattern": { "description": "Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.", "type": "string", "minLength": 1, "maxLength": 42, "pattern": "^[a-z:-]*$" }, "rule": { "$ref": "#/components/schemas/V2PolicyRule" } } }, "CreateUpdateV2PolicyRequest": { "allOf": [ { "type": "object", "required": [ "control" ], "properties": { "control": { "$ref": "#/components/schemas/Control" } } }, { "$ref": "#/components/schemas/V2PolicyBase" } ] }, "V2Policy": { "allOf": [ { "$ref": "#/components/schemas/V2PolicyBase" }, { "type": "object", "required": [ "id", "href", "control", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "state" ], "properties": { "id": { "type": "string", "description": "The policy ID.", "readOnly": true }, "href": { "description": "The href URL that links to the policies API by policy ID.", "type": "string", "readOnly": true }, "control": { "$ref": "#/components/schemas/ControlResponse" }, "created_at": { "description": "The UTC timestamp when the policy was created.", "type": "string", "format": "date-time", "readOnly": true }, "created_by_id": { "description": "The IAM ID of the entity that created the policy.", "type": "string", "readOnly": true }, "last_modified_at": { "description": "The UTC timestamp when the policy was last modified.", "type": "string", "format": "date-time", "readOnly": true }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the policy.", "type": "string", "readOnly": true }, "state": { "description": "The policy state, either 'deleted' or 'active'.", "type": "string", "enum": [ "active", "deleted" ] }, "last_permit_at": { "description": "The optional last permit time of policy, when passing query parameter format=include_last_permit.", "type": "string" }, "last_permit_frequency": { "description": "The optional count of times that policy has provided a permit, when passing query parameter format=include_last_permit.", "type": "integer" } } } ] }, "V2PolicyCollection": { "description": "A collection of policies.", "type": "object", "required": [ "policies" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "policies": { "type": "array", "description": "List of policies.", "minItems": 0, "items": { "$ref": "#/components/schemas/V2PolicyTemplateMetaData" } } } }, "V2PolicyTemplateMetaData": { "allOf": [ { "$ref": "#/components/schemas/V2Policy" }, { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/TemplateMetadata" } } } ] }, "TemplateGrantRoles": { "type": "object", "required": [ "roles" ], "properties": { "roles": { "description": "A set of role Cloud Resource Names (CRNs) granted by the policy.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Roles" } } } }, "TemplateGrantRoleReferences": { "type": "object", "required": [ "role_template_references" ], "properties": { "role_template_references": { "$ref": "#/components/schemas/RoleTemplateReferences" } } }, "TemplateGrant": { "description": "Permission is granted by the policy.", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/TemplateGrantRoles" }, { "$ref": "#/components/schemas/TemplateGrantRoleReferences" } ] }, "TemplateControl": { "description": "Specifies the type of access that is granted by the policy.", "type": "object", "required": [ "grant" ], "properties": { "grant": { "$ref": "#/components/schemas/TemplateGrant" } } }, "RoleTemplateReferences": { "description": "A set of role template reference IDs granted by the policy.", "minItems": 1, "type": "array", "items": { "description": "A role template reference associated with a policy template.", "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "description": "The role template ID.", "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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": { "type": "string", "description": "Role template version", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } } }, "TemplatePolicy": { "description": "The core set of properties associated with the template's policy object.", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The policy type; either 'access' or 'authorization'.", "enum": [ "access", "authorization" ] }, "description": { "type": "string", "description": "Description of the policy. This is shown in child accounts when an access group or trusted profile template uses the policy template to assign access.", "pattern": "^.*$", "minLength": 1, "maxLength": 300 }, "resource": { "$ref": "#/components/schemas/V2PolicyResource" }, "subject": { "$ref": "#/components/schemas/V2PolicySubject" }, "pattern": { "description": "Indicates pattern of rule, either 'time-based-conditions:once', 'time-based-conditions:weekly:all-day', or 'time-based-conditions:weekly:custom-hours'.", "type": "string", "minLength": 1, "maxLength": 42, "pattern": "^[a-z:-]*$" }, "rule": { "$ref": "#/components/schemas/V2PolicyRule" }, "control": { "$ref": "#/components/schemas/TemplateControl" } } }, "PolicyTemplateBase": { "description": "The core set of properties associated with the policy template.", "type": "object", "required": [ "name", "account_id", "policy", "version", "state" ], "properties": { "name": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "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.", "type": "string", "pattern": "^.*$", "minLength": 1, "maxLength": 300 }, "account_id": { "description": "Enterprise account ID where this template is created.", "type": "string", "minLength": 1, "maxLength": 32 }, "version": { "description": "Template version.", "type": "string", "minLength": 1, "maxLength": 2 }, "committed": { "description": "Committed status of the template version.", "type": "boolean" }, "policy": { "$ref": "#/components/schemas/TemplatePolicy" }, "state": { "description": "State of policy template.", "type": "string", "enum": [ "active", "deleted" ] } } }, "PolicyTemplateVersionRequest": { "description": "The policy template to create.", "type": "object", "required": [ "policy" ], "properties": { "name": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "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.", "type": "string", "pattern": "^.*$", "minLength": 0, "maxLength": 300 }, "policy": { "$ref": "#/components/schemas/TemplatePolicy" }, "committed": { "description": "Committed status of the template version.", "type": "boolean" } } }, "PolicyTemplateRequest": { "description": "The policy template to create.", "type": "object", "required": [ "name", "account_id", "policy" ], "properties": { "name": { "description": "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", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "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.", "type": "string", "pattern": "^.*$", "minLength": 0, "maxLength": 300 }, "account_id": { "description": "Enterprise account ID where this template is created.", "type": "string", "pattern": "^[A-Za-z0-9-]*$", "minLength": 1, "maxLength": 32 }, "committed": { "description": "Committed status of the template.", "type": "boolean" }, "policy": { "$ref": "#/components/schemas/TemplatePolicy" } } }, "PolicyTemplate": { "allOf": [ { "$ref": "#/components/schemas/PolicyTemplateBase" }, { "type": "object", "required": [ "id", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id" ], "properties": { "id": { "type": "string", "description": "The policy template ID.", "readOnly": true }, "href": { "description": "The href URL that links to the policy templates API by policy template ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the policy template was created.", "type": "string", "format": "date-time", "readOnly": true }, "created_by_id": { "description": "The IAM ID of the entity that created the policy template.", "type": "string", "readOnly": true }, "last_modified_at": { "description": "The UTC timestamp when the policy template was last modified.", "type": "string", "format": "date-time", "readOnly": true }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the policy template.", "type": "string", "readOnly": true } } } ] }, "PolicyTemplateCollection": { "description": "A collection of policy Templates.", "type": "object", "required": [ "policy_templates" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "policy_templates": { "type": "array", "description": "List of policy templates.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/PolicyTemplate" } } } }, "PolicyTemplateVersionsCollection": { "description": "A collection of versions for a specific policy template.", "type": "object", "required": [ "versions" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "versions": { "type": "array", "description": "List of policy templates versions.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/PolicyTemplate" } } } }, "LimitData": { "description": "policy template current and limit details with in an account", "type": "object", "properties": { "current": { "type": "integer", "description": "policy template current count", "readOnly": true }, "limit": { "type": "integer", "description": "policy template limit count", "readOnly": true } } }, "TemplateCountData": { "description": "policy template count details", "type": "object", "properties": { "template": { "$ref": "#/components/schemas/LimitData" }, "version": { "$ref": "#/components/schemas/LimitData" } } }, "PolicyTemplateLimitData": { "allOf": [ { "$ref": "#/components/schemas/PolicyTemplate" }, { "type": "object" }, { "properties": { "counts": { "$ref": "#/components/schemas/TemplateCountData" } } } ] }, "PolicyAssignmentStatus": { "description": "The policy assignment status.", "type": "string", "enum": [ "in_progress", "succeeded", "succeed_with_errors", "failed" ] }, "AssignmentResourceCreated": { "description": "On success, includes the policy that is assigned.", "type": "object", "properties": { "id": { "description": "Policy id", "type": "string" } } }, "PolicyAssignmentResourcePolicy": { "description": "Set of properties for the assigned resource.", "type": "object", "properties": { "resource_created": { "$ref": "#/components/schemas/AssignmentResourceCreated" }, "status": { "description": "policy status", "type": "string" }, "error_message": { "$ref": "#/components/schemas/AssignmentResourceError" } } }, "PolicyAssignmentResources": { "description": "The policy assignment resources.", "type": "object", "properties": { "target": { "description": "Account ID where resources are assigned.", "type": "string", "minLength": 1 }, "policy": { "$ref": "#/components/schemas/PolicyAssignmentResourcePolicy" } } }, "PolicyAssignmentV1Resources": { "description": "The policy assignment resources.", "type": "object", "properties": { "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "policy": { "$ref": "#/components/schemas/PolicyAssignmentResourcePolicy" } } }, "PolicyAssignmentRequest": { "description": "The core set of properties associated with the policy assignment.", "type": "object", "required": [ "template_id", "template_version", "target_type", "target" ], "properties": { "template_id": { "type": "string", "description": "policy template ID", "minLength": 1, "maxLength": 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}$" }, "template_version": { "type": "string", "description": "policy template version", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" }, "assignment_id": { "type": "string", "description": "Passed in value to correlate with other assignments", "minLength": 1, "maxLength": 122 }, "target_type": { "type": "string", "description": "Assignment target type", "minLength": 1, "maxLength": 30, "enum": [ "Account", "AccountGroup", "Enterprise" ] }, "target": { "type": "string", "description": "ID of the target account", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } } }, "AssignmentTemplateDetails": { "description": "policy template details", "type": "object", "properties": { "id": { "type": "string", "description": "Policy template ID", "minLength": 1, "maxLength": 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": { "type": "string", "description": "Policy template version", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } }, "AssignmentTargetDetails": { "description": "assignment target account and type", "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "Assignment target type", "minLength": 1, "maxLength": 30, "enum": [ "Account" ] }, "id": { "type": "string", "description": "ID of the target account", "minLength": 1, "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } } }, "PolicyAssignmentV1WithoutTemplateDetails": { "description": "The core set of properties associated with the policy assignment.", "type": "object", "required": [ "target" ], "properties": { "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" } } }, "PolicyAssignmentV1Request": { "description": "The core set of properties associated with the policy assignment.", "required": [ "templates" ], "allOf": [ { "$ref": "#/components/schemas/PolicyAssignmentV1WithoutTemplateDetails" }, { "type": "object", "properties": { "templates": { "type": "array", "minItems": 1, "maxItems": 1, "description": "List of template details for policy assignment", "items": { "$ref": "#/components/schemas/AssignmentTemplateDetails" } } } } ] }, "UpdatePolicyAssignmentRequest": { "description": "The set of properties associated with the policy template assignment.", "type": "object", "required": [ "template_version" ], "properties": { "template_version": { "type": "string", "description": "The policy template version to update to.", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } }, "PolicyAssignmentV1Subject": { "description": "Subject details of access type assignment.", "type": "object", "required": [ "id", "type" ], "properties": { "id": { "description": "The unique identifier of the subject of the assignment.", "type": "string", "minLength": 1, "pattern": "^((IBMid)|(iam-ServiceId)|(AccessGroupId)|(iam-Profile)|(SL)|([a-zA-Z0-9]{3,10}))-", "readOnly": true }, "type": { "description": "The identity type of the subject of the assignment.", "type": "string", "readOnly": true, "minLength": 1, "enum": [ "iam_id", "access_group_id" ] } } }, "PolicyAssignmentV1": { "description": "The set of properties associated with the policy template assignment.", "type": "object", "required": [ "id", "resources", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "status", "template" ], "allOf": [ { "$ref": "#/components/schemas/PolicyAssignmentV1WithoutTemplateDetails" } ], "properties": { "id": { "type": "string", "description": "Policy assignment ID.", "readOnly": true }, "account_id": { "type": "string", "description": "The account GUID that the policies assignments belong to.", "readOnly": true }, "href": { "description": "The href URL that links to the policies assignments API by policy assignment ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the policy assignment was created.", "type": "string", "format": "date-time", "readOnly": true }, "created_by_id": { "description": "The IAM ID of the entity that created the policy assignment.", "type": "string", "readOnly": true }, "last_modified_at": { "description": "The UTC timestamp when the policy assignment was last modified.", "type": "string", "format": "date-time", "readOnly": true }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the policy assignment.", "type": "string", "readOnly": true }, "resources": { "type": "array", "description": "Object for each account assigned.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/PolicyAssignmentV1Resources" } }, "subject": { "$ref": "#/components/schemas/PolicyAssignmentV1Subject" }, "template": { "$ref": "#/components/schemas/AssignmentTemplateDetails" }, "status": { "$ref": "#/components/schemas/PolicyAssignmentStatus" } } }, "PolicyAssignment": { "description": "The set of properties associated with the policy template assignment.", "type": "object", "required": [ "id", "resources", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "status" ], "allOf": [ { "$ref": "#/components/schemas/PolicyAssignmentRequest" } ], "properties": { "id": { "type": "string", "description": "Policy assignment ID.", "readOnly": true }, "account_id": { "type": "string", "description": "The account GUID that the policies assignments belong to.", "readOnly": true }, "href": { "description": "The href URL that links to the policies assignments API by policy assignment ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the policy assignment was created.", "type": "string", "format": "date-time", "readOnly": true }, "created_by_id": { "description": "The IAM ID of the entity that created the policy assignment.", "type": "string", "readOnly": true }, "last_modified_at": { "description": "The UTC timestamp when the policy assignment was last modified.", "type": "string", "format": "date-time", "readOnly": true }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the policy assignment.", "type": "string", "readOnly": true }, "resources": { "type": "array", "description": "Object for each account assigned.", "minItems": 1, "items": { "$ref": "#/components/schemas/PolicyAssignmentResources" } }, "status": { "$ref": "#/components/schemas/PolicyAssignmentStatus" } } }, "PolicyTemplateAssignmentItems": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PolicyAssignmentV1" }, { "$ref": "#/components/schemas/PolicyAssignment" } ] }, "PolicyTemplateAssignmentCollection": { "description": "A collection of policies assignments.", "type": "object", "required": [ "assignments" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "assignments": { "type": "array", "description": "List of policy assignments.", "minItems": 0, "items": { "$ref": "#/components/schemas/PolicyTemplateAssignmentItems" } } } }, "PolicyAssignmentV1Collection": { "description": "Policy assignment response.", "type": "object", "required": [ "assignments" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "assignments": { "type": "array", "description": "Response of policy assignments.", "minItems": 0, "items": { "$ref": "#/components/schemas/PolicyAssignmentV1" } } } }, "IdentityTypesBase": { "type": "object", "description": "The core set of properties associated with an identity type.", "required": [ "state", "external_allowed_accounts" ], "properties": { "state": { "type": "string", "description": "The state of the identity type.", "enum": [ "enabled", "monitor", "limited" ] }, "external_allowed_accounts": { "type": "array", "description": "List of accounts that the state applies to for a given identity.", "minItems": 0, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "description": "Account ID .", "pattern": "^[A-Za-z0-9-_]+$", "minLength": 1, "maxLength": 1024 } } } }, "IdentityTypes": { "type": "object", "description": "The settings for each identity type.", "required": [ "user", "service_id", "service" ], "properties": { "user": { "$ref": "#/components/schemas/IdentityTypesBase" }, "service_id": { "$ref": "#/components/schemas/IdentityTypesBase" }, "service": { "$ref": "#/components/schemas/IdentityTypesBase" } } }, "ExternalAccountIdentityInteraction": { "type": "object", "description": "How external accounts can interact in relation to the requested account.", "required": [ "identity_types" ], "properties": { "identity_types": { "$ref": "#/components/schemas/IdentityTypes" } } }, "AccountSettingsAccessManagement": { "type": "object", "description": "The Access Management Account Settings that are currently set for the requested account.", "required": [ "external_account_identity_interaction" ], "properties": { "external_account_identity_interaction": { "$ref": "#/components/schemas/ExternalAccountIdentityInteraction" } } }, "IdentityTypesPatch": { "type": "object", "description": "The settings to apply for each identity type for a request.", "properties": { "user": { "$ref": "#/components/schemas/IdentityTypesBase" }, "service_id": { "$ref": "#/components/schemas/IdentityTypesBase" }, "service": { "$ref": "#/components/schemas/IdentityTypesBase" } } }, "ExternalAccountIdentityInteractionPatch": { "type": "object", "description": "Update to how external accounts can interact in relation to the requested account.", "properties": { "identity_types": { "$ref": "#/components/schemas/IdentityTypesPatch" } } }, "AccountSettingsAccessManagementPatch": { "description": "The set of Access Management Account Settings properties to be updated for the requested account.", "type": "object", "properties": { "external_account_identity_interaction": { "$ref": "#/components/schemas/ExternalAccountIdentityInteractionPatch" } } }, "TemplateActionControl": { "description": "The action control properties that are created in an action resource when the template is assigned.", "type": "object", "required": [ "service_name", "actions" ], "properties": { "service_name": { "type": "string", "description": "The service name that the action control refers.", "minLength": 1, "maxLength": 300 }, "description": { "type": "string", "description": "Description of the action control.", "pattern": "^.*$", "minLength": 1, "maxLength": 300 }, "actions": { "type": "array", "description": "List of actions to control access.", "minItems": 1, "maxItems": 10, "items": { "type": "string", "description": "IAM action ID.", "minLength": 5, "maxLength": 100 } } } }, "ActionControlTemplateVersionPrototype": { "description": "The action control template version required to create a new version of an existing action control template.", "type": "object", "properties": { "name": { "description": "Required field when creating a new template. Otherwise, this field is optional. If the field is included, it will change the name value for all existing versions of the template.", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.", "type": "string", "pattern": "^.*$", "minLength": 0, "maxLength": 300 }, "action_control": { "$ref": "#/components/schemas/TemplateActionControl" }, "committed": { "description": "Committed status of the template version. If committed is set to true, then the template version can no longer be updated.", "type": "boolean" } } }, "ActionControlTemplatePrototype": { "description": "The action control template to create.", "type": "object", "required": [ "name", "account_id" ], "properties": { "name": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "Description of the action control template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the action control for enterprise users managing IAM templates.", "type": "string", "pattern": "^.*$", "minLength": 0, "maxLength": 300 }, "account_id": { "description": "Enterprise account ID where this template is created.", "type": "string", "pattern": "^[A-Za-z0-9-]*$", "minLength": 1, "maxLength": 32 }, "committed": { "description": "Committed status of the template. If committed is set to true, then the template version can no longer be updated.", "type": "boolean" }, "action_control": { "$ref": "#/components/schemas/TemplateActionControl" } } }, "ActionControlTemplate": { "description": "The set of properties associated with the action control template.", "allOf": [ { "$ref": "#/components/schemas/ActionControlTemplatePrototype" }, { "type": "object", "required": [ "id", "description", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "version", "state" ], "properties": { "id": { "type": "string", "description": "The action control template ID.", "readOnly": true, "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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}$" }, "href": { "description": "The href URL that links to the action control templates API by action control template ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the action control template was created.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "created_by_id": { "description": "The IAM ID of the entity that created the action control template.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "last_modified_at": { "description": "The UTC timestamp when the action control template was last modified.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the action control template.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "version": { "description": "The version number of the template used to identify different versions of same template.", "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" }, "state": { "description": "State of action control template.", "type": "string", "enum": [ "active", "deleted" ] } } } ] }, "ActionControlTemplateCollection": { "description": "A collection of action control templates.", "type": "object", "required": [ "action_control_templates" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "action_control_templates": { "type": "array", "description": "List of action control templates.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/ActionControlTemplate" } } } }, "ActionControlTemplateVersionsCollection": { "description": "A collection of versions for a specific action control template.", "type": "object", "required": [ "versions" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "versions": { "type": "array", "description": "List of action control templates versions.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/ActionControlTemplate" } } } }, "ActionControlAssignmentStatus": { "description": "The action control assignment status.", "type": "string", "readOnly": true, "enum": [ "accepted", "failure", "in_progress", "superseded" ] }, "ActionControlAssignmentResourceCreated": { "description": "On success, it includes the action control assigned.", "type": "object", "properties": { "id": { "description": "action control id", "type": "string" } } }, "ActionControlAssignmentResourceActionControl": { "description": "Set of properties of the assigned resource or error message if assignment failed.", "type": "object", "properties": { "resource_created": { "$ref": "#/components/schemas/ActionControlAssignmentResourceCreated" }, "error_message": { "$ref": "#/components/schemas/AssignmentResourceError" } } }, "ActionControlAssignmentResource": { "description": "The action control assignment resources and target where the template is assigned.", "type": "object", "required": [ "target" ], "properties": { "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "action_control": { "$ref": "#/components/schemas/ActionControlAssignmentResourceActionControl" } } }, "ActionControlAssignmentTemplate": { "description": "The action control template id and version that will be assigned.", "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "description": "Action control template ID.", "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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": { "type": "string", "description": "Action control template version.", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } }, "ActionControlAssignmentPrototype": { "description": "The action control assignment to create.", "required": [ "templates", "target" ], "type": "object", "properties": { "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "templates": { "type": "array", "minItems": 1, "maxItems": 1, "description": "List of action control template details for action control assignment.", "items": { "$ref": "#/components/schemas/ActionControlAssignmentTemplate" } } } }, "ActionControlAssignmentPatchTemplate": { "type": "object", "description": "The template version to update the assignment to.", "required": [ "template_version" ], "properties": { "template_version": { "type": "string", "description": "The version number of the template used to identify different versions of same template.", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } }, "ActionControlAssignment": { "description": "The set of properties associated with the assigned action control template.", "type": "object", "required": [ "id", "resources", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "status", "operation", "template", "target" ], "properties": { "id": { "type": "string", "description": "Action control assignment ID.", "readOnly": true, "minLength": 1, "maxLength": 62, "pattern": "^actionControlAssignment-[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}$" }, "account_id": { "type": "string", "description": "The account GUID that the action control assignments belong to.", "readOnly": true }, "href": { "description": "The href URL that links to the action control assignments API by action control assignment ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the action control assignment was created.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "created_by_id": { "description": "The IAM ID of the entity that created the action control assignment.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "last_modified_at": { "description": "The UTC timestamp when the action control assignment was last modified.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the action control assignment.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "operation": { "description": "The current operation of the action control assignment", "type": "string", "readOnly": true, "enum": [ "create", "apply", "update", "remove" ] }, "resources": { "type": "array", "description": "Resources created when action control template is assigned.", "readOnly": true, "minItems": 1, "items": { "$ref": "#/components/schemas/ActionControlAssignmentResource" } }, "template": { "$ref": "#/components/schemas/ActionControlAssignmentTemplate" }, "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "status": { "$ref": "#/components/schemas/ActionControlAssignmentStatus" } } }, "ActionControlAssignmentCollection": { "description": "A collection of action control assignments.", "type": "object", "required": [ "assignments" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "assignments": { "type": "array", "description": "List of action control assignments.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/ActionControlAssignment" } } } }, "AssignmentResourceError": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the error" }, "errorCode": { "type": "string", "description": "error code" }, "message": { "type": "string", "description": "Error message detailing the nature of the error" }, "code": { "type": "string", "description": "Internal status code for the error" }, "errors": { "description": "The errors encountered during the response.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/ErrorObject" } } }, "description": "Body parameters for assignment error" }, "TemplateRole": { "description": "The role properties that are created in an action resource when the template is assigned.", "type": "object", "required": [ "display_name", "actions" ], "properties": { "display_name": { "type": "string", "description": "The display the name of the role that is shown in the console", "minLength": 1, "maxLength": 50, "pattern": "^((?!<|>).)*$" }, "service_name": { "type": "string", "description": "The service name that the role refers.", "minLength": 1, "maxLength": 300 }, "description": { "type": "string", "description": "Description of the role.", "pattern": "^.*$", "minLength": 1, "maxLength": 300 }, "actions": { "type": "array", "description": "The actions of the role.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "description": "IAM action ID.", "minLength": 1 } } } }, "RoleTemplateVersionPrototype": { "description": "The role template version required to create a new version of an existing role template.", "type": "object", "properties": { "name": { "description": "Required field when creating a new template. Otherwise, this field is optional. If the field is included, it will change the name value for all existing versions of the template.", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.", "type": "string", "pattern": "^.*$", "minLength": 0, "maxLength": 300 }, "role": { "$ref": "#/components/schemas/TemplateRole" }, "committed": { "description": "Committed status of the template version. If committed is set to true, then the template version can no longer be updated.", "type": "boolean" } } }, "RoleTemplatePrototype": { "description": "The role template to create.", "type": "object", "required": [ "name", "account_id" ], "properties": { "name": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "description": { "description": "Description of the role template. This is shown to users in the enterprise account. Use this to describe the purpose or context of the role for enterprise users managing IAM templates.", "type": "string", "pattern": "^.*$", "minLength": 0, "maxLength": 300 }, "account_id": { "description": "Enterprise account ID where this template is created.", "type": "string", "pattern": "^[A-Za-z0-9-]*$", "minLength": 1, "maxLength": 32 }, "committed": { "description": "Committed status of the template. If committed is set to true, then the template version can no longer be updated.", "type": "boolean" }, "role": { "allOf": [ { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the role that is used in the CRN. This must be alphanumeric and capitalized.", "minLength": 1, "maxLength": 30, "pattern": "^[A-Z]{1}[A-Za-z0-9]{0,29}$" } } }, { "$ref": "#/components/schemas/TemplateRole" } ] } } }, "RoleTemplate": { "description": "The set of properties associated with the role template.", "allOf": [ { "$ref": "#/components/schemas/RoleTemplatePrototype" }, { "type": "object", "required": [ "id", "description", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "version", "state" ], "properties": { "id": { "type": "string", "description": "The role template ID.", "readOnly": true, "minLength": 1, "maxLength": 49, "pattern": "^roleTemplate-[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}$" }, "href": { "description": "The href URL that links to the role templates API by role template ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the role template was created.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "created_by_id": { "description": "The IAM ID of the entity that created the role template.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "last_modified_at": { "description": "The UTC timestamp when the role template was last modified.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the role template.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "version": { "description": "The version number of the template used to identify different versions of same template.", "type": "string", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" }, "state": { "description": "State of role template.", "type": "string", "enum": [ "active", "deleted" ] } } } ] }, "RoleTemplateCollection": { "description": "A collection of role templates.", "type": "object", "required": [ "role_templates" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "role_templates": { "type": "array", "description": "List of role templates.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/RoleTemplate" } } } }, "RoleTemplateVersionsCollection": { "description": "A collection of versions for a specific role template.", "type": "object", "required": [ "versions" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "versions": { "type": "array", "description": "List of role templates versions.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/RoleTemplate" } } } }, "RoleAssignmentStatus": { "description": "The role assignment status.", "type": "string", "readOnly": true, "enum": [ "accepted", "failure", "in_progress", "superseded" ] }, "RoleAssignmentResourceCreated": { "description": "On success, it includes the role assigned.", "type": "object", "properties": { "id": { "description": "role id", "type": "string" } } }, "RoleAssignmentResourceRole": { "description": "Set of properties of the assigned resource or error message if assignment failed.", "type": "object", "properties": { "resource_created": { "$ref": "#/components/schemas/RoleAssignmentResourceCreated" }, "error_message": { "$ref": "#/components/schemas/AssignmentResourceError" } } }, "RoleAssignmentResource": { "description": "The role assignment resources and target where the template is assigned.", "type": "object", "required": [ "target" ], "properties": { "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "role": { "$ref": "#/components/schemas/RoleAssignmentResourceRole" } } }, "RoleAssignmentTemplate": { "description": "The role template id and version that will be assigned.", "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "description": "Action control template ID.", "minLength": 1, "maxLength": 58, "pattern": "^actionControlTemplate-[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": { "type": "string", "description": "Action control template version.", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } }, "RoleAssignmentPrototype": { "description": "The role assignment to create.", "required": [ "templates", "target" ], "type": "object", "properties": { "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "templates": { "type": "array", "minItems": 1, "maxItems": 1, "description": "List of role template details for role assignment.", "items": { "$ref": "#/components/schemas/RoleAssignmentTemplate" } } } }, "RoleAssignmentPatchTemplate": { "type": "object", "description": "The template version to update the assignment to.", "required": [ "template_version" ], "properties": { "template_version": { "type": "string", "description": "The version number of the template used to identify different versions of same template.", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]*$" } } }, "RoleAssignment": { "description": "The set of properties associated with the assigned role template.", "type": "object", "required": [ "id", "resources", "href", "created_at", "created_by_id", "last_modified_at", "last_modified_by_id", "status", "operation", "template", "target" ], "properties": { "id": { "type": "string", "description": "Action control assignment ID.", "readOnly": true, "minLength": 1, "maxLength": 62, "pattern": "^actionControlAssignment-[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}$" }, "account_id": { "type": "string", "description": "The account GUID that the role assignments belong to.", "readOnly": true }, "href": { "description": "The href URL that links to the role assignments API by role assignment ID.", "type": "string", "readOnly": true }, "created_at": { "description": "The UTC timestamp when the role assignment was created.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "created_by_id": { "description": "The IAM ID of the entity that created the role assignment.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "last_modified_at": { "description": "The UTC timestamp when the role assignment was last modified.", "type": "string", "format": "date-time", "readOnly": true, "minLength": 16, "maxLength": 24 }, "last_modified_by_id": { "description": "The IAM ID of the entity that last modified the role assignment.", "type": "string", "readOnly": true, "minLength": 1, "maxLength": 250 }, "operation": { "description": "The current operation of the role assignment", "type": "string", "readOnly": true, "enum": [ "create", "apply", "update", "remove" ] }, "resources": { "type": "array", "description": "Resources created when role template is assigned.", "readOnly": true, "minItems": 1, "items": { "$ref": "#/components/schemas/RoleAssignmentResource" } }, "template": { "$ref": "#/components/schemas/RoleAssignmentTemplate" }, "target": { "$ref": "#/components/schemas/AssignmentTargetDetails" }, "status": { "$ref": "#/components/schemas/RoleAssignmentStatus" } } }, "RoleAssignmentCollection": { "description": "A collection of role assignments.", "type": "object", "required": [ "assignments" ], "properties": { "limit": { "$ref": "#/components/schemas/Limit" }, "first": { "$ref": "#/components/schemas/First" }, "next": { "$ref": "#/components/schemas/Next" }, "previous": { "$ref": "#/components/schemas/Previous" }, "assignments": { "type": "array", "description": "List of role assignments.", "minItems": 0, "maxItems": 100, "items": { "$ref": "#/components/schemas/RoleAssignment" } } } } } } }