Skip to main content
Version: 4.0.3

Assign many users to a user group

POST 
/groups-srv/bulk/usergroups/:groupId/users

This API call bulk-assigns users to one existing user group (groupId in the path). Membership is unique on (sub, groupId): a user is never added to the same group twice.

This endpoint always uses upsert. There is no instruction field (unlike POST /groups-srv/usergroups/maps/{sub}). Users omitted from the request are not removed from the group.

If the user is already a member:

  • The existing membership is updated, not skipped and not duplicated
  • roles in the request replace the user's current roles in this group (they are not merged)
  • updatedTime is refreshed; this is not a silent no-op even if the roles are unchanged

If the user is not a member:

  • A new membership is created

Operation Behavior:

  • Processes multiple user group maps in a single API call
  • All user group maps must reference the same groupId as specified in the path parameter
  • Each user group map in the array is processed independently
  • The operation continues processing even if individual items fail

Validation Rules:

  • Request body must be a valid JSON array
  • Array must contain at least one user group map object
  • All user group maps must have groupId matching the path parameter
  • Each user group map must comply with validation rules:
    • sub: Required, must be a valid user ID (UUID format), user must exist
    • groupId: Required, must match the path parameter exactly
    • roles: Optional array, all roles must exist and be allowed by the group's groupType

Business Rules:

  • All user group maps in the batch must reference the same groupId as the path parameter
  • Role validation follows the same rules as individual user group map creation
  • The operation is not fully atomic - some items may succeed while others fail
  • Check the response to identify which user assignments were successful and which failed

Related endpoints:

  • POST /groups-srv/usergroups/maps/{sub} — assign one user to many groups (instruction required)
  • GET /groups-srv/usergroups/maps/{sub} — list a user's current memberships
  • DELETE /groups-srv/usergroups/{groupId}/users/{sub} — remove one membership

Request​

Responses​

OK - Bulk operation completed. Check the response for individual success/failure status of each user assignment.