Skip to main content

Assign User to Groups

Endpoint​

/i/groups/save-user-group

Ⓔ Enterprise Only
This API is available exclusively in Countly Enterprise.

Overview​

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

Authentication​

  • Authentication methods:
    • API Key (parameter): api_key=YOUR_API_KEY
    • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
    • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

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

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/Processing​

  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.

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

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":[]}

Ⓔ Enterprise​

This feature is part of Countly Enterprise.

Get Access:

Already a Customer? Use support portal if you have any questions

Last Updated​

2026-02-16