Skip to main content

Assign User to Groups

Enterprise

This endpoint is part of Countly Enterprise. To get access, contact sales or compare versions. Existing customers can reach the support portal with questions.

Endpoint​

/i/groups/save-user-group

Overview​

Assigns a user to one or more groups, or clears all user group assignments when group_id is omitted/empty.

Authentication​

Pass api_key or auth_token as a query parameter, or send countly-token as a header. See Authentication.

Permissions​

  • Required access: global admin

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or auth_token)API key authentication
auth_tokenStringYes (or api_key)Auth token authentication
argsObject (JSON string)YesStringified assignment object

args Object Fields​

FieldTypeRequiredDescription
emailStringYesUser email
group_idArrayNoGroup IDs to assign. Empty/omitted removes all group assignments

Examples​

Example 1: Assign User to Two Groups​

Endpoint form:

https://your-server.com/i/groups/save-user-group?api_key=YOUR_API_KEY&args={"email":"analyst@example.com","group_id":["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]}

Decoded args object:

{
  "email": "analyst@example.com",
  "group_id": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

Example 2: Remove User from All Groups​

Endpoint form:

https://your-server.com/i/groups/save-user-group?api_key=YOUR_API_KEY&args={"email":"analyst@example.com","group_id":[]}

Response​

Success Response​

{
  "result": "Success"
}

Response Fields​

FieldTypeDescription
resultStringOperation status

Error Responses​

HTTP StatusResponse
200{ "result": "Not enough args" }
400{ "result": "User Not found" }
400{ "result": "group_id is wrong!" }
400{ "result": "Cannot add Global Admin to group" }
400{ "result": "Missing parameter \"api_key\" or \"auth_token\"" }

Behavior​

  1. Validates user by email.
  2. When group_id is provided, validates groups and merges permissions from target groups.
  3. Synchronizes both sides of membership (members.group_id and groups.users).
  4. When group_id is missing/empty, removes all group assignments from the user.
Implementation details

Database Collections

CollectionUsed forData touched by this endpoint
countly.membersEndpoint data source** - User group assignments and effective permissions
countly.groupsEndpoint data source** - Group user list synchronization