# Groups

## Retrieving all groups

> Retrieves all groups of the tenant. You can filter the results by using query parameters.\
> \
> The \`iam.group\_read\_own\` scope allows customers to retrieve only groups of \`CUSTOMER\` type.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.group_read","iam.group_read_own"]}],"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_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_name_query_param":{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Search by the name of a given resource. The value is conformed against all of the specified accepted languages.\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_description_query_param":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Search by the description of the the given resource, it is conformed against all of the specified accepted-languages."},"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"},"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}/groups":{"get":{"tags":["Groups"],"summary":"Retrieving all groups","description":"Retrieves all groups of the tenant. You can filter the results by using query parameters.\n\nThe `iam.group_read_own` scope allows customers to retrieve only groups of `CUSTOMER` type.\n","operationId":"GET-iam-list-tenant-user-groups","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_name_query_param"},{"$ref":"#/components/parameters/trait_q_query_param"},{"$ref":"#/components/parameters/trait_description_query_param"},{"$ref":"#/components/parameters/trait_metadataModifiedAt_query_param"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"},{"$ref":"#/components/parameters/X-Total-Count"},{"schema":{"type":"string"},"in":"query","name":"userType","description":"Search by the group user type. Possible values are: `CUSTOMER` and `EMPLOYEE`"}],"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"}}}}}}
```

## Creating a new group

> Creates a new group. When a group is created, you can assign particular users to it. Based on the group's access controls list, you can grant members specific system access.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Groups"}],"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.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_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":{"GroupCreateRequest":{"type":"object","properties":{"id":{"type":"string","description":"Custom group's identifier. If not provided, it is automatically generated"},"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},"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."},"mixins":{"type":"object","additionalProperties":true,"description":"Custom group attributes that need to be included directly in the `mixins` object."},"accessControls":{"type":"array","description":"Access control unique identifiers associated with this group. Required to perform the request.","nullable":true,"items":{"type":"string"}},"userType":{"type":"string","description":"The type of the group. Possible values: 'CUSTOMER', 'EMPLOYEE'. Default value 'EMPLOYEE' if not provided.","default":"EMPLOYEE","enum":["CUSTOMER","EMPLOYEE"],"nullable":true},"templates":{"type":"array","description":"Template unique identifier associated with this group. Required to perform the request.","nullable":true,"items":{"type":"string"}},"b2b":{"type":"object","description":"Additional properties for B2B.","properties":{"legalEntityId":{"type":"string","description":"Identifier of the assigned legal entity."}}},"restrictions":{"$ref":"#/components/schemas/Restrictions"}},"required":["name"]},"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"}},"GroupIdResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the generated document."}}},"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_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"}}}}}}}}}},"Conflict_409":{"description":"Resource with given id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/iam/{tenant}/groups":{"post":{"tags":["Groups"],"summary":"Creating a new group","description":"Creates a new group. When a group is created, you can assign particular users to it. Based on the group's access controls list, you can grant members specific system access.\n","operationId":"POST-iam-create-user-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/trait_contentLanguage_header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupCreateRequest"}}},"required":true,"description":""},"responses":{"201":{"description":"The request was successful. The group has been created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupIdResponse"}}}},"400":{"$ref":"#/components/responses/Bad_request_400_cl"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"description":"Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"$ref":"#/components/responses/Conflict_409"}}}}}}
```

## Retrieving a group

> Retrieves a specified group's details.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Groups"}],"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.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"}},"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}/groups/{groupId}":{"get":{"tags":["Groups"],"summary":"Retrieving a group","description":"Retrieves a specified group's details.\n","operationId":"GET-iam-retrieve-users-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. Group details are 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"}}}}}}}}}
```

## Upserting a group

> Updates a user group, or creates a new one if a group with a specified if doesn't exist yet. If you provide the \`metadata.version\`, the optimistic locking is enabled and version is validated.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Groups"}],"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.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_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":{"GroupUpdateRequest":{"type":"object","properties":{"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."},"mixins":{"type":"object","additionalProperties":true,"description":"Custom group attributes that need to be included directly in the `mixins` object."},"accessControls":{"type":"array","description":"Access control unique identifiers associated with this group. Required to perform the request.","nullable":true,"items":{"type":"string"}},"userType":{"type":"string","description":"The type of the group. Possible values: 'CUSTOMER', 'EMPLOYEE'. Default value 'EMPLOYEE' if not provided","default":"EMPLOYEE","enum":["CUSTOMER","EMPLOYEE"],"nullable":true},"templates":{"type":"array","description":"Template unique identifier associated with this group. Required to perform the request.","nullable":true,"items":{"type":"string"}},"b2b":{"type":"object","description":"additional properties for B2B","properties":{"legalEntityId":{"type":"string","description":"identifier of the assigned legal entity"}}},"restrictions":{"$ref":"#/components/schemas/Restrictions"},"metadata":{"type":"object","properties":{"version":{"type":"integer","format":"int32","description":"Version of the entity, If provided optimistic locking is enabled and its version must match the version of the document in the database."}},"description":"Metadata of the updated group."}},"required":["name"]},"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"}},"GroupIdResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of the generated document."}}},"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"}}}}}}}}}}}},"paths":{"/iam/{tenant}/groups/{groupId}":{"put":{"tags":["Groups"],"summary":"Upserting a group","description":"Updates a user group, or creates a new one if a group with a specified if doesn't exist yet. If you provide the `metadata.version`, the optimistic locking is enabled and version is validated.\n","operationId":"PUT-iam-update-user-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/trait_contentLanguage_header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupUpdateRequest"}}},"required":true,"description":""},"responses":{"201":{"description":"The request was successful. The group has been created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupIdResponse"}}}},"204":{"description":"The request was successful. The group has been updated."},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"description":"Permission denied due to insufficient rights. This may happen when request does not contain sufficient scopes for given query values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Deleting a group

> Deletes a specified group.\
> \
> \*\*\*Important\*\*\*: If you want to delete a group that has users assigned to it, you need to set the \`forceDelete\` query parameter to \`true\`. In this case, all user group assignments are deleted as well. The force flag requires the \`iam.assignment\_manage\` scope. The \`iam.assignment\_manage\` scope is only required if you want to delete a group that has users assigned to it.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.group_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":{"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"}},"groupId":{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of a group, generated when the group is created."}},"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}/groups/{groupId}":{"delete":{"tags":["Groups"],"summary":"Deleting a group","description":"Deletes a specified group.\n\n***Important***: If you want to delete a group that has users assigned to it, you need to set the `forceDelete` query parameter to `true`. In this case, all user group assignments are deleted as well. The force flag requires the `iam.assignment_manage` scope. The `iam.assignment_manage` scope is only required if you want to delete a group that has users assigned to it.\n","operationId":"DELETE-iam-remove-user-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"},{"name":"forceDelete","in":"query","description":"* If set to `true` and the group has users assigned to it, both the group and the group assignments will be deleted.\n\n  **Important**: To set this parameter to true, you must request an access token with the `iam.assignment_manage` scope.\n\n* If set to `false` or not specified and the group has users assigned to it, the endpoint will respond with the 400 error.\n","schema":{"type":"boolean","default":false}}],"responses":{"204":{"description":"The request was successful. The group has been deleted."},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"resourceId":{"type":"string"},"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Retrieving all access controls assigned to a group

> Retrieves all access controls assigned to a specified group. Based on that list all users assigned to this group will receive specific system access. 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":"Groups"}],"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"}},"groupId":{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of a group, generated when the group 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_expand_query_param":{"name":"expand","in":"query","required":false,"schema":{"type":"string","enum":["role,resource","resource,role","role","resource"]},"description":"Adds expanded resource and/or role objects to the response."},"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","description":"Role unique identifier associated with this access control."},"resourceId":{"type":"string","description":"Resource unique identifier associated with this access control."},"domain":{"type":"string","description":"Domain identifier associated with this access control."},"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."},"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}/groups/{groupId}/access-controls":{"get":{"tags":["Groups"],"summary":"Retrieving all access controls assigned to a group","description":"Retrieves all access controls assigned to a specified group. Based on that list all users assigned to this group will receive specific system access. You can expand the result by resolving the role and resource references.\n","operationId":"GET-iam-list-group-access-controls","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/X-Total-Count"},{"$ref":"#/components/parameters/trait_expand_query_param"},{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. A list of group 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 users assigned to a group

> Retrieves users assignments for a specified group.\
> \
> The \`iam.user\_read\_own\` scope allows customer to retrieve only users assignments from a specified group but only from the same company assignment<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Groups"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.user_read","iam.user_read_own"]}],"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"}},"groupId":{"name":"groupId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of a group, generated when the group 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"}},"schemas":{"AssignmentQueryDocument":{"type":"object","properties":{"id":{"type":"string","description":"Assignment unique identifier generated when the assignment is created."},"groupId":{"type":"string","description":"User unique identifiers associated with this assignment."},"userId":{"type":"string","description":"Group unique identifiers associated with this assignment."},"userType":{"type":"string","description":"User type that may be one of: 'CUSTOMER', 'EMPLOYEE'"}},"description":"Definition of assignments"},"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}/groups/{groupId}/users":{"get":{"tags":["Groups"],"summary":"Retrieving users assigned to a group","description":"Retrieves users assignments for a specified group.\n\nThe `iam.user_read_own` scope allows customer to retrieve only users assignments from a specified group but only from the same company assignment\n","operationId":"GET-iam-list-group-users","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/X-Total-Count"}],"responses":{"200":{"description":"The request was successful. A list of user IDs is returned.","headers":{"X-Total-Count":{"description":"Total number of retrieved users.","schema":{"type":"integer","format":"int32"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentQueryDocument"}}}}},"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"}}}}}}}}}
```