> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-documentation/api-guides/users-and-permissions/iam/api-reference/users.md).

# Users

## Retrieving all access controls assigned to a user

> Retrieves all access controls assigned to a specified user.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Users"}],"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.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.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"}},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user is created."},"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"}},"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."},"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."},"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."}}},"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}/users/{userId}/access-controls":{"get":{"tags":["Users"],"summary":"Retrieving all access controls assigned to a user","description":"Retrieves all access controls assigned to a specified user.\n","operationId":"GET-iam-list-user-access-controls","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/userId"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/X-Total-Count"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. A list of user 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"},"404":{"description":"Given resources cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Retrieving all groups to which a user is assigned

> Retrieves all groups to which a specified user is assigned.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.group_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.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.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"}},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user is created."},"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_sort":{"name":"sort","in":"query","description":"List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.\n\nPossible values:\n* `{fieldName}`\n* `{fieldName}:asc`\n* `{fieldName}:desc`\n\n**Note:** If you want to sort the results by localized properties, the possible values are as follows:\n  * `{fieldName}.{language}`\n  * `{fieldName}.{language}:asc`\n  * `{fieldName}.{language}:desc`\n\nIf the sorting direction is not specified, the fields are sorted in ascending order.","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"},"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"}},"schemas":{"GroupsQueryDocument":{"type":"object","properties":{"id":{"type":"string","description":"Group unique identifier generated when the group is created."},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized group name in the form of a map of translations."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized group description in the form of a map of translations."},"vendorId":{"type":"string","description":"An identifier of a vendor to whom the group belongs. Can only be set during creation and is immutable thereafter. A group with vendorId can only be assigned to users of type `EMPLOYEE`","readOnly":true},"accessControls":{"type":"array","description":"Access control unique identifiers associated with this group.","items":{"type":"string"}},"templates":{"type":"array","description":"Template unique identifiers associated with this group.","items":{"type":"string"}},"code":{"type":"string"},"userType":{"type":"string","description":"The group type determines if the group can consist of users of the `CUSTOMER` or the `EMPLOYEE` type."},"b2b":{"type":"object","description":"additional properties for B2B","properties":{"legalEntityId":{"type":"string","description":"identifier of the assigned legal entity"}}},"restrictions":{"$ref":"#/components/schemas/Restrictions"},"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom group attributes that need to be included directly in the `mixins` object."},"metadata":{"$ref":"#/components/schemas/GroupsMetadataQueryDocument"}},"description":"Definition of groups"},"Restrictions":{"type":"array","items":{"type":"string","description":"Limits the visibility of the permission-aware entities for the user. \n\n**Purpose**: \nRestricts entity visibility based on scope permissions. Only users with matching restriction scopes can access entity with a specific restriction value.\n\n**Validation**: \nThe value must exist in the tenant's configured list of valid restrictions.\n**Site Synchronization**: \nWhen enabled via tenant configuration (`enableSyncBetweenRestrictionsAndSiteCodes` property), this field must match with the existing sites.\n"}},"GroupsMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Group document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the group was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the group was last modified.","format":"date-time"}},"description":"Group 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}/users/{userId}/groups":{"get":{"tags":["Users"],"summary":"Retrieving all groups to which a user is assigned","description":"Retrieves all groups to which a specified user is assigned.\n","operationId":"GET-iam-retrieve-user-groups","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/userId"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"},{"$ref":"#/components/parameters/X-Total-Count"}],"responses":{"200":{"description":"The request was successful. A list of groups is returned.","headers":{"X-Total-Count":{"description":"Total number of retrieved groups.","schema":{"type":"integer","format":"int32"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupsQueryDocument"}}}}},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Retrieving user group info

> Retrieves user specific group.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.group_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.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.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"}},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user is created."},"groupId":{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of a group, generated when the group is created."},"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":{"GroupsQueryDocument":{"type":"object","properties":{"id":{"type":"string","description":"Group unique identifier generated when the group is created."},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized group name in the form of a map of translations."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized group description in the form of a map of translations."},"vendorId":{"type":"string","description":"An identifier of a vendor to whom the group belongs. Can only be set during creation and is immutable thereafter. A group with vendorId can only be assigned to users of type `EMPLOYEE`","readOnly":true},"accessControls":{"type":"array","description":"Access control unique identifiers associated with this group.","items":{"type":"string"}},"templates":{"type":"array","description":"Template unique identifiers associated with this group.","items":{"type":"string"}},"code":{"type":"string"},"userType":{"type":"string","description":"The group type determines if the group can consist of users of the `CUSTOMER` or the `EMPLOYEE` type."},"b2b":{"type":"object","description":"additional properties for B2B","properties":{"legalEntityId":{"type":"string","description":"identifier of the assigned legal entity"}}},"restrictions":{"$ref":"#/components/schemas/Restrictions"},"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom group attributes that need to be included directly in the `mixins` object."},"metadata":{"$ref":"#/components/schemas/GroupsMetadataQueryDocument"}},"description":"Definition of groups"},"Restrictions":{"type":"array","items":{"type":"string","description":"Limits the visibility of the permission-aware entities for the user. \n\n**Purpose**: \nRestricts entity visibility based on scope permissions. Only users with matching restriction scopes can access entity with a specific restriction value.\n\n**Validation**: \nThe value must exist in the tenant's configured list of valid restrictions.\n**Site Synchronization**: \nWhen enabled via tenant configuration (`enableSyncBetweenRestrictionsAndSiteCodes` property), this field must match with the existing sites.\n"}},"GroupsMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Group document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the group was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the group was last modified.","format":"date-time"}},"description":"Group 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}/users/{userId}/groups/{groupId}":{"get":{"tags":["Users"],"summary":"Retrieving user group info","description":"Retrieves user specific group.\n","operationId":"GET-iam-retrieve-user-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/userId"},{"$ref":"#/components/parameters/groupId"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. The group is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupsQueryDocument"}}}},"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"}}}}}}}}}
```

## Retrieving scopes of a specific user

> Retrieves all scopes granted to a user specified by id. Those are calculated based on user group assignments. For each particular group all access controls are resolved to scopes based on defined role(s) and resource(s).<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.scope_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.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.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"}},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user is created."}},"schemas":{"UserScopesResponse":{"type":"object","properties":{"userId":{"type":"string","description":"User unique identifier."},"scopes":{"type":"string","description":"User scopes."},"vendorId":{"type":"string","description":"An identifier of a vendor to whom the user belongs. Calculated based on groups assignment","readOnly":true}},"description":"Definition of user scopes"}},"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}/users/{userId}/scopes":{"get":{"tags":["Users"],"summary":"Retrieving scopes of a specific user","description":"Retrieves all scopes granted to a user specified by id. Those are calculated based on user group assignments. For each particular group all access controls are resolved to scopes based on defined role(s) and resource(s).\n","operationId":"GET-iam-retrieve-user-scopes","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/userId"}],"responses":{"200":{"description":"The request was successful. A list of scopes is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserScopesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Retrieving all access controls assigned to a requested user

> Retrieves all access controls assigned to a requested user.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"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.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.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"}},"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."},"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."},"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."}}},"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}/users/me/access-controls":{"get":{"tags":["Users"],"summary":"Retrieving all access controls assigned to a requested user","description":"Retrieves all access controls assigned to a requested user.\n","operationId":"GET-iam-retrieve-user-access-controls","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/X-Total-Count"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. A list of user 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"},"404":{"description":"Given resources cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Retrieving scopes of a requested user

> Retrieves all own scopes granted to the user sending the request. Those are calculated based on user group assignments. For each particular group all access controls are resolved to scopes based on defined role(s) and resource(s).<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"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.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.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"}}},"schemas":{"UserScopesResponse":{"type":"object","properties":{"userId":{"type":"string","description":"User unique identifier."},"scopes":{"type":"string","description":"User scopes."},"vendorId":{"type":"string","description":"An identifier of a vendor to whom the user belongs. Calculated based on groups assignment","readOnly":true}},"description":"Definition of user scopes"}},"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}/users/me/scopes":{"get":{"tags":["Users"],"summary":"Retrieving scopes of a requested user","description":"Retrieves all own scopes granted to the user sending the request. Those are calculated based on user group assignments. For each particular group all access controls are resolved to scopes based on defined role(s) and resource(s).\n","operationId":"GET-iam-retrieve-own-user-scopes","parameters":[{"$ref":"#/components/parameters/tenant"}],"responses":{"200":{"description":"The request was successful. A list of scopes is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserScopesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/api-documentation/api-guides/users-and-permissions/iam/api-reference/users.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
