> 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-references/readme/api-reference-16/groups-assignments.md).
# Groups Assignments
Manage IAM group assignments to segments
## Retrieving all group assignments for a customer segment
> Retrieves all IAM group assignments for a given customer segment.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Groups Assignments","description":"Manage IAM group assignments to segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customersegment.segment_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customersegment.segment_manage":"Needed to create or update customer segments.","customersegment.segment_read":"Needed to read customer segments.","customersegment.segment_read_own":"Needed to read own customer segments."}}}}},"parameters":{"qParam":{"in":"query","name":"q","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n","schema":{"type":"string"}},"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the pageSize parameter."},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."}},"schemas":{"GroupAssignmentResponse":{"type":"object","properties":{"segmentId":{"type":"string","description":"Unique identifier of the customer segment."},"group":{"$ref":"#/components/schemas/Group"},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"Group":{"type":"object","description":"IAM group assigned to the customer segment.","properties":{"id":{"type":"string","description":"Unique identifier of an existing IAM group, generated when the group is created through the IAM Service."},"name":{"type":"object","description":"Localized name of the group.","additionalProperties":{"type":"string"}}}},"MetadataResponse":{"allOf":[{"type":"object","properties":{"createdAt":{"description":"The creation date.","type":"string","format":"date-time"},"modifiedAt":{"description":"The modification date.","type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/MetadataUpdate"}]},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}/groups":{"get":{"summary":"Retrieving all group assignments for a customer segment","tags":["Groups Assignments"],"operationId":"GET-customer-segment-retrieve-groups","description":"Retrieves all IAM group assignments for a given customer segment.\n","parameters":[{"$ref":"#/components/parameters/qParam"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/xTotalCount"}],"responses":{"200":{"description":"Group assignments for a customer segment were successfully retrieved.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupAssignmentResponse"}}}}},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}}}}}}
```
## Searching with parameters for group assignments
> Returns all IAM group assignments that match the provided criteria.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Groups Assignments","description":"Manage IAM group assignments to segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customersegment.segment_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customersegment.segment_manage":"Needed to create or update customer segments.","customersegment.segment_read":"Needed to read customer segments.","customersegment.segment_read_own":"Needed to read own customer segments."}}}}},"parameters":{"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the pageSize parameter."},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."}},"schemas":{"SegmentsSearch":{"type":"object","properties":{"q":{"type":"string","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"}}},"GroupAssignmentResponse":{"type":"object","properties":{"segmentId":{"type":"string","description":"Unique identifier of the customer segment."},"group":{"$ref":"#/components/schemas/Group"},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"Group":{"type":"object","description":"IAM group assigned to the customer segment.","properties":{"id":{"type":"string","description":"Unique identifier of an existing IAM group, generated when the group is created through the IAM Service."},"name":{"type":"object","description":"Localized name of the group.","additionalProperties":{"type":"string"}}}},"MetadataResponse":{"allOf":[{"type":"object","properties":{"createdAt":{"description":"The creation date.","type":"string","format":"date-time"},"modifiedAt":{"description":"The modification date.","type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/MetadataUpdate"}]},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}/groups/search":{"post":{"summary":"Searching with parameters for group assignments","tags":["Groups Assignments"],"operationId":"POST-customer-segment-search-groups","description":"Returns all IAM group assignments that match the provided criteria.\n","parameters":[{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/xTotalCount"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentsSearch"}}}},"responses":{"200":{"description":"Group assignments for a customer segment were successfully retrieved.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupAssignmentResponse"}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}}}}}}
```
## Retrieving a group assignment for a customer segment
> Retrieves an IAM group assignment for a specified group and customer segment.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Groups Assignments","description":"Manage IAM group assignments to segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customersegment.segment_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customersegment.segment_manage":"Needed to create or update customer segments.","customersegment.segment_read":"Needed to read customer segments.","customersegment.segment_read_own":"Needed to read own customer segments."}}}}},"parameters":{"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."}},"schemas":{"GroupAssignmentResponse":{"type":"object","properties":{"segmentId":{"type":"string","description":"Unique identifier of the customer segment."},"group":{"$ref":"#/components/schemas/Group"},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"Group":{"type":"object","description":"IAM group assigned to the customer segment.","properties":{"id":{"type":"string","description":"Unique identifier of an existing IAM group, generated when the group is created through the IAM Service."},"name":{"type":"object","description":"Localized name of the group.","additionalProperties":{"type":"string"}}}},"MetadataResponse":{"allOf":[{"type":"object","properties":{"createdAt":{"description":"The creation date.","type":"string","format":"date-time"},"modifiedAt":{"description":"The modification date.","type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/MetadataUpdate"}]},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_NotFound_404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}/groups/{groupId}":{"get":{"summary":"Retrieving a group assignment for a customer segment","tags":["Groups Assignments"],"operationId":"GET-customer-segment-retrieve-group","description":"Retrieves an IAM group assignment for a specified group and customer segment.\n","parameters":[{"$ref":"#/components/parameters/fields"}],"responses":{"200":{"description":"Group assignment for a customer segment was successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupAssignmentResponse"}}}},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/Common_response_NotFound_404"}}}}}}
```
## Upserting a group assignment for a customer segment
> Performs an \`UPSERT\` operation. Updates an IAM group assignment for a customer segment. Creates the assignment if it is not present in the system.\
> \
> Only IAM groups with \`userType\` \`CUSTOMER\` can be assigned to a segment.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Groups Assignments","description":"Manage IAM group assignments to segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customersegment.segment_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customersegment.segment_manage":"Needed to create or update customer segments.","customersegment.segment_read":"Needed to read customer segments.","customersegment.segment_read_own":"Needed to read own customer segments."}}}}},"schemas":{"GroupAssignmentUpsert":{"type":"object","description":"Request body for creating or updating an IAM group assignment.\n","properties":{"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true},"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Conflict_409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}/groups/{groupId}":{"put":{"summary":"Upserting a group assignment for a customer segment","tags":["Groups Assignments"],"operationId":"PUT-customer-segment-update-group","description":"Performs an `UPSERT` operation. Updates an IAM group assignment for a customer segment. Creates the assignment if it is not present in the system.\n\nOnly IAM groups with `userType` `CUSTOMER` can be assigned to a segment.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupAssignmentUpsert"}}}},"responses":{"201":{"description":"A new group assignment was successfully created."},"204":{"description":"Group assignment was successfully updated."},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"},"409":{"$ref":"#/components/responses/Common_response_Conflict_409"}}}}}}
```
## Removing a group from a customer segment
> Removes an IAM group assignment from a customer segment.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Groups Assignments","description":"Manage IAM group assignments to segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["customersegment.segment_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"customersegment.segment_manage":"Needed to create or update customer segments.","customersegment.segment_read":"Needed to read customer segments.","customersegment.segment_read_own":"Needed to read own customer segments."}}}}},"responses":{"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}/groups/{groupId}":{"delete":{"summary":"Removing a group from a customer segment","tags":["Groups Assignments"],"operationId":"DELETE-customer-segment-remove-group","description":"Removes an IAM group assignment from a customer segment.\n","responses":{"204":{"description":"Group assignment was successfully removed."},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_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-references/readme/api-reference-16/groups-assignments.md?ask=&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.