# Group Assignments
## Adding a user to a group
> Assigns a user to a specified group. The user gains all access controls (scopes) specified for this group.\
> \
> Groups assigned to employee users must share the same vendor identifier.\
> \
> The \`iam.assignment\_create\_own\` scope allows a customer to assign a user to a specified group only if the user is assigned to the same company.
```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Group Assignments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.assignment_manage","iam.assignment_create_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."}},"schemas":{"AssignmentCreateRequest":{"type":"object","properties":{"userId":{"type":"string","description":"User unique identifier generated when the user is created. Might be customer ID or Management Dashboard user ID."},"userType":{"type":"string","enum":["CUSTOMER","EMPLOYEE"],"default":"EMPLOYEE","description":"Assignment type, possible values: CUSTOMER, EMPLOYEE"}},"required":["userId"]},"AssignmentIdResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of 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":{"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":{"post":{"tags":["Group Assignments"],"summary":"Adding a user to a group","description":"Assigns a user to a specified group. The user gains all access controls (scopes) specified for this group.\n\nGroups assigned to employee users must share the same vendor identifier.\n\nThe `iam.assignment_create_own` scope allows a customer to assign a user to a specified group only if the user is assigned to the same company.\n","operationId":"POST-iam-add-user-to-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentCreateRequest"}}},"required":true},"responses":{"201":{"description":"The request was successful. The user has been added to the group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentIdResponse"}}}},"400":{"description":"Request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}}}}}}}
```
## Removing all users from a group
> Removes all users from a specified group.
```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Group Assignments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.assignment_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}/users":{"delete":{"tags":["Group Assignments"],"summary":"Removing all users from a group","description":"Removes all users from a specified group.\n","operationId":"DELETE-iam-remove-all-users","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"}],"responses":{"204":{"description":"The request was successful. All users have been deleted from the group."},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```
## Upserting user assignment to a group
> Creates user's assignment to a specified group. The user gains all access controls (scopes) specified for this group.\
> In case the assignment already exists, nothing happens as the type of assignment cannot be changed.\
> \
> Groups assigned to employee users must share the same vendor identifier
```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Group Assignments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.assignment_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."},"userType":{"name":"userType","in":"path","required":true,"schema":{"type":"string"},"description":"User type that may be one of: 'CUSTOMER', 'EMPLOYEE'"},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user is created."}},"schemas":{"AssignmentIdResponse":{"type":"object","properties":{"id":{"type":"string","description":"ID of 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":{"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/{userType}/{userId}":{"put":{"tags":["Group Assignments"],"summary":"Upserting user assignment to a group","description":"Creates user's assignment to a specified group. The user gains all access controls (scopes) specified for this group.\nIn case the assignment already exists, nothing happens as the type of assignment cannot be changed.\n\nGroups assigned to employee users must share the same vendor identifier\n","operationId":"PUT-iam-update-user-to-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"},{"$ref":"#/components/parameters/userType"},{"$ref":"#/components/parameters/userId"}],"responses":{"201":{"description":"The request was successful. The user has been added to the group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentIdResponse"}}}},"204":{"description":"The request was successful. The user assignment already exists and has not been changed."},"400":{"description":"Request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}}}}}}}
```
## Removing a user from a group
> Removes a specified user from a specified group. \
> \
> The \`iam.assignment\_delete\_own\` scope allows a customer to remove user from a specified group only if the user is assigned to the same company.
```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Group Assignments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.assignment_manage","iam.assignment_delete_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."},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user 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}/users/{userId}":{"delete":{"tags":["Group Assignments"],"summary":"Removing a user from a group","description":"Removes a specified user from a specified group. \n\nThe `iam.assignment_delete_own` scope allows a customer to remove user from a specified group only if the user is assigned to the same company.\n","operationId":"DELETE-iam-remove-user-from-group","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/groupId"},{"$ref":"#/components/parameters/userId"}],"responses":{"204":{"description":"The request was successful. The user has been removed from the group."},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```
## Removing a user from all groups
> Removes a specified user from all groups.
```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Group Assignments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.assignment_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"}},"userId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User unique identifier, generated when the user 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"}}}}}}}}}}},"schemas":{"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"}}}}}},"paths":{"/iam/{tenant}/users/{userId}/groups":{"delete":{"tags":["Group Assignments"],"summary":"Removing a user from all groups","description":"Removes a specified user from all groups.\n","operationId":"DELETE-iam-remove-user-from-all-groups","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/userId"}],"responses":{"204":{"description":"The request was successful. The user has been removed from all groups."},"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"}}}}}}}}}
```
---
# 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/group-assignments.md?ask=
```
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.