Skip to main content
Version: 4.0.2

Assign the user to multiple User Groups

POST 
/groups-srv/usergroups/maps/:sub

Assign or change multiple group memberships for one user in a single request. Use the instruction field to control how each entry in userGroupMaps is handled. Memberships not listed in the request are never added or removed by this call alone.

Instructions (choose one):

InstructionWhen to useEffect on listed groupsEffect on other memberships for this user
insertAdd groups without changing existing membershipsCreates a new membership per entryLeft unchanged
updateChange roles only where the user is already a memberUpdates roles for existing (sub, groupId) onlyLeft unchanged
upsertAdd or change roles in one callCreates missing memberships; updates roles if already a memberLeft unchanged
replaceAllUpdate roles for listed groups only (same as update per entry)Updates roles for existing (sub, groupId) onlyLeft unchanged

Per-instruction details:

  • insert: Creates new memberships only. If (sub, groupId) already exists, that entry is skipped and reported in the bulk response (other entries still process).
  • update: Updates roles for existing memberships only. Does not create new memberships. Entries without an existing map fail for that item only.
  • upsert: Creates the membership if it does not exist, or updates roles (including clearing roles when an empty roles array is sent) if it does.
  • replaceAll: Behaves like update for each listed group — updates roles where membership already exists; does not create new memberships and does not remove groups omitted from the list.

Choosing an instruction:

  • Add the user to more groups → insert
  • Change roles when membership already exists → update
  • Add groups or change roles (membership may or may not exist) → upsert

Setting an exact membership list (recommended design):

This endpoint does not remove unlisted groups in one step. Compose calls as needed:

  • Adjust a few groups: GET /groups-srv/usergroups/maps/{sub} to read current memberships, then DELETE /groups-srv/usergroups/{groupId}/users/{sub} for each group to remove, and POST this endpoint with upsert (or insert for add-only) for the desired set.
  • Replace the full set: DELETE /groups-srv/usergroups/maps/{sub} to remove all memberships for the user, then POST with instruction: upsert and the complete userGroupMaps list.

Request body:

  • instruction (required): One of insert, update, upsert, replaceAll
  • userGroupMaps (required): Non-empty array of memberships to process

Validation rules:

  • Path sub is required and identifies the user.
  • Each map should use the same sub as the path parameter (or omit sub so the path value applies).
  • groupId must reference an existing user group.
  • roles must comply with the group's groupType roleMode (when roles are provided).

Response behavior:

  • Returns a bulk result with per-entry status. HTTP 200 when the request is processed; individual entries may succeed, fail, or be skipped depending on instruction and validation.
  • This is not all-or-nothing: one invalid groupId does not roll back successful entries unless a fatal error aborts the request.

Related endpoints:

  • GET /groups-srv/usergroups/maps/{sub} — list current memberships
  • DELETE /groups-srv/usergroups/{groupId}/users/{sub} — remove one membership
  • DELETE /groups-srv/usergroups/maps/{sub} — remove all memberships for a user (optional transfer via request body)

Request​

Responses​

OK