# Access Controls

## Retrieving all access controls

> Retrieves all access controls available for the tenant. The results can be filtered by using query parameters. You can expand the result by resolving the role and resource references.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Access Controls"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.access_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Your Emporix tenant name.\n\n**Note**: The tenant name should always be written in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}},"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"Page number to be retrieved. The number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"Number of items to be retrieved per page.\n","schema":{"default":60,"minimum":1,"type":"integer"}},"trait_metadataModifiedAt_query_param":{"name":"metadataModifiedAt","in":"query","required":false,"schema":{"type":"string"},"description":"Search by given resources that contain the `metadata.modifiedAt` date field with a date later than the specified value. The format is as follows: ''yyyy-MM-dd''.\n"},"roleId_query":{"name":"roleId","in":"query","deprecated":true,"description":"Search by access controls with the `roleId` field equal to the specified value.\n\n**Note**: This query parameter is deprecated.\n","schema":{"type":"string"}},"trait_resourceId_query_param":{"name":"resourceId","in":"query","required":false,"deprecated":true,"schema":{"type":"string"},"description":"Search by the id of a given resource.\n\n**Note**: This query parameter is deprecated.\n"},"trait_q_query_param":{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Standard query parameter used to search for specific values.   \n* Searching for an item by string property: `q=id:31065d5b-b62e`, where `id` is the field name and `31065d5b-b62e` is its required value.   \n* Searching for an item by localized field property: `q=name.en:T-s` where `name` is the name of the field, `en` is a language code and `T-s` is a required value of this field.   This query works only for localized fields, which are stored in a Map format where `key` is a language code and `value` is translation to particular language.   + Searching for items by date property. All numer-based property queries are valid also for dates. In that case the date should be placed within double quotes: `q=metadata.createdAt:(>=\"2021-05-18T07:27:27.455Z\" AND <\"2021-05-20T07:27:27.455Z\")`   + Searching for items with non existing or empty property: `q=name.en:null` where `name.en` is a name of fields that has value `null`.   + Searching for items with existing property: `q=attributes:exists` where `attributes` is a name of field that has `non null` value.   + Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)` where `id` is name of field and strings within a bracket are it''s required value.   + Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f name.en:T-s` where `id` and ''name.en'' are the names of fields. All documents that contain given values of these fields are returned. Multiple fields separated by space can be specified. Multiple values for each field can be also specified in a format presented above.   + Searching for items with string fields conforming to a regex: `q=name.en:~ABCD12` or `q=name.en:(~AB CD)` - in case of searching for strings with space, where `name` is the name of field and `ABCD12` or `AB CD` is it''s querying regex.'\n"},"trait_expand_query_param":{"name":"expand","in":"query","required":false,"deprecated":true,"schema":{"type":"string","enum":["role,resource","resource,role","role","resource"]},"description":"Adds expanded resource and/or role objects to the response.\n\n**Note**: This query parameter is deprecated.\n"},"X-Total-Count":{"name":"X-Total-Count","in":"header","required":false,"schema":{"type":"boolean","default":false},"description":"Flag indicating whether the total number of retrieved items should be returned.\n"},"trait_acceptLanguage_header":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If the value is specified, then it must be present in the tenant configuration.\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.\n* If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"}},"schemas":{"AccessControlQueryDocument":{"type":"object","description":"Definition of access control","properties":{"id":{"type":"string","description":"Assignment unique identifier generated when the assignment is created."},"roleId":{"type":"string","deprecated":true,"description":"Role unique identifier associated with this access control."},"resourceId":{"type":"string","deprecated":true,"description":"Resource unique identifier associated with this access control."},"domains":{"type":"array","description":"Domain identifiers associated with this access control.","items":{"type":"string"}},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized resource name in the form of a map of translations."},"role":{"$ref":"#/components/schemas/RoleQueryDocument"},"resource":{"$ref":"#/components/schemas/ResourceQueryDocument"},"metadata":{"$ref":"#/components/schemas/AccessControlMetadataQueryDocument"},"scopes":{"type":"array","description":"A list of resolved scopes for a particular access control.","items":{"type":"string"}},"restrictionAware":{"type":"boolean","description":"Determines whether this access control generates scopes with restriction suffixes when assigned to a group that has restrictions defined. When `true`, the generated scopes will include restrictions (e.g. order.`order_manage--DE`) based on the group's restrictions list. When `false`, scopes are generated without restriction suffixes regardless of the group's restrictions."},"restrictedTo":{"type":"string","enum":["CUSTOMER","EMPLOYEE"],"description":"Restricts the type of group this access control can be assigned to.\n* `CUSTOMER` - the access control can be assigned only to groups of `CUSTOMER` user type.\n* `EMPLOYEE` - the access control can be assigned only to groups of `EMPLOYEE` user type.\n\nIf this property is not present, the access control can be assigned to any group regardless of its user type.\n"},"predefined":{"type":"boolean","readOnly":true,"description":"Indicated whether this access control is predefined in the system or was created by a user."},"vendorAware":{"type":"boolean","readOnly":true,"description":"Indicated whether this access control is associated with vendor scopes."}}},"RoleQueryDocument":{"type":"object","description":"Role definition associated with this access control.","properties":{"id":{"type":"string","description":"Role unique identifier generated when the role is created."},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized role name in the form of a map of translations."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized role description in the form of a map of translations."},"permissions":{"type":"array","description":"Permissions unique identifier list declared for this role.","items":{"$ref":"#/components/schemas/RolePermissionsDocument"}},"metadata":{"$ref":"#/components/schemas/RolesMetadata"}}},"RolePermissionsDocument":{"type":"object","description":"Role permissions list.","title":"","properties":{"applicablePermissionResources":{"type":"array","description":"Allows you to allowlist resources that the permission is applicable to. Can only contain resources specified in the permission document under `applicableResources`.\n","items":{"type":"string"}},"id":{"type":"string","description":"Reference to the permission document with specific resources defined."}},"required":["id"]},"RolesMetadata":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Role document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the role was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the role was last modified.","format":"date-time"}}},"ResourceQueryDocument":{"type":"object","properties":{"id":{"type":"string","description":"Resource unique identifier generated when the resource is created."},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized resource name in the form of a map of translations."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized resource description in the form of a map of translations."},"code":{"type":"string","description":"Resource unique code identifier."},"metadata":{"$ref":"#/components/schemas/ResourcesMetadataQueryDocument"}},"description":"Resource definition associated with this access control."},"ResourcesMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Resource document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the resource was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the resource was last modified.","format":"date-time"}},"description":"Resource metadata."},"AccessControlMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Access control document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the access control was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the access control was last modified.","format":"date-time"}},"description":"Access control metadata."}},"responses":{"Bad_request_400":{"description":"Unsupported language provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/access-controls":{"get":{"tags":["Access Controls"],"summary":"Retrieving all access controls","description":"Retrieves all access controls available for the tenant. The results can be filtered by using query parameters. You can expand the result by resolving the role and resource references.\n","operationId":"GET-iam-list-tenant-access-controls","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_metadataModifiedAt_query_param"},{"$ref":"#/components/parameters/roleId_query"},{"$ref":"#/components/parameters/trait_resourceId_query_param"},{"$ref":"#/components/parameters/trait_q_query_param"},{"$ref":"#/components/parameters/trait_expand_query_param"},{"$ref":"#/components/parameters/X-Total-Count"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. A list of access controls is returned.","headers":{"X-Total-Count":{"description":"Total number of retrieved access controls.","schema":{"type":"integer","format":"int32"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AccessControlQueryDocument"}}}}},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Retrieving an access control

> Retrieves details of a specified access control. You can expand the result by resolving the role and resource references.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Access Controls"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.access_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Your Emporix tenant name.\n\n**Note**: The tenant name should always be written in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}},"access_control_Id":{"name":"accessControlId","in":"path","description":"Unique identifier of an access control.","required":true,"schema":{"type":"string"}},"trait_acceptLanguage_header":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If the value is specified, then it must be present in the tenant configuration.\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.\n* If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"},"trait_expand_query_param":{"name":"expand","in":"query","required":false,"deprecated":true,"schema":{"type":"string","enum":["role,resource","resource,role","role","resource"]},"description":"Adds expanded resource and/or role objects to the response.\n\n**Note**: This query parameter is deprecated.\n"}},"schemas":{"AccessControlQueryDocument":{"type":"object","description":"Definition of access control","properties":{"id":{"type":"string","description":"Assignment unique identifier generated when the assignment is created."},"roleId":{"type":"string","deprecated":true,"description":"Role unique identifier associated with this access control."},"resourceId":{"type":"string","deprecated":true,"description":"Resource unique identifier associated with this access control."},"domains":{"type":"array","description":"Domain identifiers associated with this access control.","items":{"type":"string"}},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized resource name in the form of a map of translations."},"role":{"$ref":"#/components/schemas/RoleQueryDocument"},"resource":{"$ref":"#/components/schemas/ResourceQueryDocument"},"metadata":{"$ref":"#/components/schemas/AccessControlMetadataQueryDocument"},"scopes":{"type":"array","description":"A list of resolved scopes for a particular access control.","items":{"type":"string"}},"restrictionAware":{"type":"boolean","description":"Determines whether this access control generates scopes with restriction suffixes when assigned to a group that has restrictions defined. When `true`, the generated scopes will include restrictions (e.g. order.`order_manage--DE`) based on the group's restrictions list. When `false`, scopes are generated without restriction suffixes regardless of the group's restrictions."},"restrictedTo":{"type":"string","enum":["CUSTOMER","EMPLOYEE"],"description":"Restricts the type of group this access control can be assigned to.\n* `CUSTOMER` - the access control can be assigned only to groups of `CUSTOMER` user type.\n* `EMPLOYEE` - the access control can be assigned only to groups of `EMPLOYEE` user type.\n\nIf this property is not present, the access control can be assigned to any group regardless of its user type.\n"},"predefined":{"type":"boolean","readOnly":true,"description":"Indicated whether this access control is predefined in the system or was created by a user."},"vendorAware":{"type":"boolean","readOnly":true,"description":"Indicated whether this access control is associated with vendor scopes."}}},"RoleQueryDocument":{"type":"object","description":"Role definition associated with this access control.","properties":{"id":{"type":"string","description":"Role unique identifier generated when the role is created."},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized role name in the form of a map of translations."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized role description in the form of a map of translations."},"permissions":{"type":"array","description":"Permissions unique identifier list declared for this role.","items":{"$ref":"#/components/schemas/RolePermissionsDocument"}},"metadata":{"$ref":"#/components/schemas/RolesMetadata"}}},"RolePermissionsDocument":{"type":"object","description":"Role permissions list.","title":"","properties":{"applicablePermissionResources":{"type":"array","description":"Allows you to allowlist resources that the permission is applicable to. Can only contain resources specified in the permission document under `applicableResources`.\n","items":{"type":"string"}},"id":{"type":"string","description":"Reference to the permission document with specific resources defined."}},"required":["id"]},"RolesMetadata":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Role document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the role was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the role was last modified.","format":"date-time"}}},"ResourceQueryDocument":{"type":"object","properties":{"id":{"type":"string","description":"Resource unique identifier generated when the resource is created."},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized resource name in the form of a map of translations."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized resource description in the form of a map of translations."},"code":{"type":"string","description":"Resource unique code identifier."},"metadata":{"$ref":"#/components/schemas/ResourcesMetadataQueryDocument"}},"description":"Resource definition associated with this access control."},"ResourcesMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Resource document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the resource was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the resource was last modified.","format":"date-time"}},"description":"Resource metadata."},"AccessControlMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Access control document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the access control was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the access control was last modified.","format":"date-time"}},"description":"Access control metadata."},"ErrorResponse":{"required":["code","message","status"],"type":"object","properties":{"resourceId":{"type":"string","nullable":true},"code":{"type":"integer","format":"int32"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}},"responses":{"Bad_request_400":{"description":"Unsupported language provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/access-controls/{accessControlId}":{"get":{"tags":["Access Controls"],"summary":"Retrieving an access control","description":"Retrieves details of a specified access control. You can expand the result by resolving the role and resource references.\n","operationId":"GET-iam-retrieve-access-control","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/access_control_Id"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"},{"$ref":"#/components/parameters/trait_expand_query_param"}],"responses":{"200":{"description":"The request was successful. Access control details are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessControlQueryDocument"}}}},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"description":"Given resources cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Upserting an access control

> Creates an access control when it does not exist, or updates it when it already exists for the tenant.\
> If \`metadata.version\` is provided, optimistic locking is applied for updates.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Access Controls"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.access_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"parameters":{"trait_contentLanguage_header":{"in":"header","name":"Content-Language","required":true,"description":"The Content-Language request HTTP header defines language(s) of the payload.","schema":{"type":"string"}}},"schemas":{"AccessControlUpsertRequest":{"type":"object","description":"Payload for creating or updating an access control.","required":["scopes"],"properties":{"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized name as a map of language codes to text."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized description as a map of language codes to text."},"scopes":{"type":"array","description":"Scope codes for this access control. Must not be empty.","minItems":1,"uniqueItems":true,"items":{"type":"string"}},"domains":{"type":"array","description":"Domain identifiers for the access control.","items":{"type":"string"}},"restrictedTo":{"type":"string","enum":["CUSTOMER","EMPLOYEE"],"description":"Restricts the type of group this access control can be assigned to.\n* `CUSTOMER` - the access control can be assigned only to groups of `CUSTOMER` user type.\n* `EMPLOYEE` - the access control can be assigned only to groups of `EMPLOYEE` user type.\n\nIf this property is not present, the access control can be assigned to any group regardless of its user type.\n\n**Note**: This property is immutable. It can only be set when the access control is created and cannot be changed afterwards.\n"},"metadata":{"type":"object","description":"Metadata for optimistic locking on updates. Only `version` is supported.","properties":{"version":{"type":"integer","format":"int32","description":"Document version. When provided on update, must match the stored version."}},"additionalProperties":false}}},"AccessControlIdResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the created access control. Matches the `accessControlId` path parameter."}}}},"responses":{"Bad_request_400_cl":{"description":"Unsupported content language provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/access-controls/{accessControlId}":{"put":{"tags":["Access Controls"],"summary":"Upserting an access control","description":"Creates an access control when it does not exist, or updates it when it already exists for the tenant.\nIf `metadata.version` is provided, optimistic locking is applied for updates.\n","operationId":"PUT-iam-upsert-access-control","parameters":[{"$ref":"#/components/parameters/trait_contentLanguage_header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessControlUpsertRequest"}}}},"responses":{"201":{"description":"The request was successful. The access control has been created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessControlIdResponse"}}}},"204":{"description":"The request was successful. The access control has been updated."},"400":{"$ref":"#/components/responses/Bad_request_400_cl"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Deleting an access control

> Deletes a specified access control.\
> \
> \*\*Note\*\*: Only user-created access controls can be deleted. Predefined access controls cannot be removed.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Access Controls"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.access_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/access-controls/{accessControlId}":{"delete":{"tags":["Access Controls"],"summary":"Deleting an access control","description":"Deletes a specified access control.\n\n**Note**: Only user-created access controls can be deleted. Predefined access controls cannot be removed.\n","operationId":"DELETE-iam-delete-access-control","responses":{"204":{"description":"The request was successful. The access control has been deleted."},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/api-references/api-guides/users-and-permissions/iam/api-reference/access-controls.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.