Skip Navigation Links

User Group Assignments

Endpoint Overview

POST /api/admin/users/v4/user-groups/assignments/batch
Assign multiple users to user groups
DELETE /api/admin/users/v4/user-groups/assignments/batch
Delete multiple user group assignments
GET /api/admin/users/v4/user-groups/{group_id}/assignable-roles
List Assignable Roles
GET /api/admin/users/v4/user-groups/{group_id}/assignments
List user group assignments
POST /api/admin/users/v4/user-groups/{group_id}/assignments
Create user group assignment
GET /api/admin/users/v4/user-groups/{group_id}/assignments/{user_id}/{role_id}
Get user group assignment
DELETE /api/admin/users/v4/user-groups/{group_id}/assignments/{user_id}/{role_id}
Delete user group assignment

Assign multiple users to user groups

Requires authentication via bearer.

Allows an admin to assign multiple users to one or multiple user groups at once.

Batch Semantics:

  • Operations are non-atomic: each assignment is processed independently
  • Partial success is possible - some assignments may succeed while others fail
  • Maximum 100 assignments per request
  • Each result contains a status code (201=success, 4xx=failure with error details)

Use Cases:

  • Bulk onboarding of users to a department group
  • Assigning multiple users the same role across different groups

Query Params

embed string[]

Options for embedding additional data in single user group assignment responses:

  • ACTIONS: Include available actions for the assignment

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

items object[]

Response Body

200 OK

Delete multiple user group assignments

Requires authentication via bearer.

Allows an admin to remove multiple users from groups at once.

Batch Semantics:

  • Operations are non-atomic: each deletion is processed independently
  • Partial success is possible - some deletions may succeed while others fail
  • Maximum 100 deletions per request
  • Each result contains a status code (200=success, 4xx=failure with error details)

Constraints:

  • Cannot delete rule-based assignments (source=RULE) - these are managed by rules
  • Cannot delete primary assignments (source=PRIMARY) - use user update instead

Request Body

items object[]

Response Body

200 OK

List Assignable Roles

Requires authentication via bearer.

Returns all roles that can be assigned to the user group by the current actor. These roles are scoped to USER_GROUPS.

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

sort string[]
page_number integer

requested page for offset based pagination. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

embed string[]

Options for embedding additional data in assignable roles responses:

  • ROLE: Include full role reference details (title, description)

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

List user group assignments

Requires authentication via bearer.

Get all user assignments for the given user group.

Note: Each assignment represents a single user-role combination. A user can have multiple assignments in the same group with different roles.

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

search_term string

A term that needs a match in the user's first name, last name or department.

role_ids string[]

Unique identifier of a role.

sort string[]

Sort options for user group assignments:

  • USER_FIRST_NAME_ASC/DESC: Sort by assigned user's first name
  • USER_LAST_NAME_ASC/DESC: Sort by assigned user's last name
page_number integer

requested page for offset based pagination. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

embed string[]

Options for embedding additional data in user group assignments list responses:

  • ACTIONS: Include available actions for assignments and list-level actions

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Create user group assignment

Requires authentication via bearer.

Assign a user to a group with a defined role.

Constraints:

  • The role must have USER_GROUPS permission scope
  • Duplicate assignments (same user, group, and role) are not allowed
  • The user must exist and be active

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

embed string[]

Options for embedding additional data in single user group assignment responses:

  • ACTIONS: Include available actions for the assignment

Request Body

role_id stringrequired

Unique identifier of a role.

user_id stringrequired

Unique identifier of a user.

Response Body

201 Created

Error Codes

  • ROLE_DOES_NOT_EXIST
  • ROLE_HAS_WRONG_PERMISSION_SCOPE
  • USER_GROUP_ASSIGNMENT_ALREADY_EXISTS

Get user group assignment

Requires authentication via bearer.

Returns a single user group assignment

Path Params

group_id stringrequired

Unique identifier of a user group.

user_id stringrequired

Unique identifier of a user.

role_id stringrequired

Unique identifier of a role.

Query Params

embed string[]

Options for embedding additional data in single user group assignment responses:

  • ACTIONS: Include available actions for the assignment

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Delete user group assignment

Requires authentication via bearer.

Delete a specific user group assignment

Path Params

group_id stringrequired

Unique identifier of a user group.

user_id stringrequired

Unique identifier of a user.

role_id stringrequired

Unique identifier of a role.

Response Body

200 OK

Error Codes

  • DERIVED_ASSIGNMENT_DELETION_FORBIDDEN