User Group

User groups are entities that aggregate multiple users based on specific conditions and/or users added explicitly. These groups can be granted permissions within applications and services that are part of the project, provided those resources are available in the given project.

Retrieve, Create, Edit, and Delete Group

Retrieves a list of groups, creates a new group, updates an existing one, or deletes a group.

Access Requirements

Retrieve ("get"): projectID/groups/groupID/group.can_manage_group. Only groups satisfying this rule are included in the response.
Create or edit ("save"): projectID/project.can_manage_groups. When a new group is created, the project tag is automatically assigned.
Delete ("delete"): projectID/project.can_manage_groups.

Note

The "save" action does not update the group’s tags or access configuration. Use the dedicated Set Group Tags and Save Group Access Settings methods for those.

Group title requirements: Latin letters (A–Z, a–z), digits (0–9), spaces, and underscores. Maximum length: 32 characters.

Request

POST /api/permissions/group

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

jwt string required 

User’s JWT token.
factor string conditionally required 

User device factor. Required if service_jwt is not provided.
service_jwt string conditionally required 

Service JWT. Required if factor is not provided.
action string required 

Action to perform. Allowed values: "get", "save", "delete".
group_id string optional 

Group ObjectID. Required when updating or deleting an existing group.
data object required 
- project_id string required 
  
  Project ID.
- title string optional 
  
  Group title. Required for "save".
- description string optional 
  
  Group description.

Request example

POST /api/permissions/group

Headers

Authorization: Bearer eyJhbGci...
Factor: ...

Body (get)

{
  "action": "get",
  "data": {
    "project_id": "my_project"
  }
}

Body (save)

{
  "action": "save",
  "data": {
    "project_id": "my_project",
    "title": "Test group",
    "description": "Test group description"
  }
}

Response

OK

Success

status string required 
- “OK”
data object optional 

For "get": object with groups array and max_users_cnt. For "save": the updated group object. Not returned for "delete".

"get" response fields:
- groups array of objects required 
  
  List of groups.
  - id string required 
    
    Group ObjectID.
  - project_id string required 
    
    ID of the project the group belongs to.
  - title string required 
    
    Group title.
  - description string optional 
    
    Group description.
  - tags array of strings optional 
    
    List of tags assigned to the group.
  - conditions array of objects optional 
    
    List of conditions for automatic group membership.
  - users array of strings optional 
    
    List of explicitly added user IDs.
- max_users_cnt integer required 
  
  Maximum number of users allowed per group in this project.

Response example (get)

{
  "status": "OK",
  "data": {
    "groups": [
      {
        "id": "...",
        "project_id": "my_project",
        "title": "Test group",
        "description": "Test group description",
        "tags": ["internal"],
        "conditions": [
          {
            "title": "Internal users",
            "condition": {"domain": "example.com"}
          }
        ],
        "users": ["uid1", "uid2"]
      }
    ],
    "max_users_cnt": 100
  }
}

Response example (delete)

{
  "status": "OK"
}

ERROR

Error

status string required 
- “ERROR”
error string required 

Descriptive error message.

Response example

{
  "status": "ERROR",
  "error": "group not found"
}

Set Group Tags

Replaces the existing tag list for a group with a new one.

Access Requirements

The request author must have a positive can_manage_project_tags rule. Additional tag parameters are checked in the params field of the rule.

Request

POST /api/permissions/group/tags

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

jwt string required 

User’s JWT token.
factor string conditionally required 

User device factor. Required if service_jwt is not provided.
service_jwt string conditionally required 

Service JWT. Required if factor is not provided.
group_id string required 

Group ObjectID.
data object required 
- title string required 
  
  Group title.
- tags array of strings required 
  
  New list of tags. Replaces the existing tags entirely.

Request example

POST /api/permissions/group/tags

Headers

Authorization: Bearer eyJhbGci...
Factor: ...

Body

{
  "group_id": "<objectID>",
  "data": {
    "title": "Test group",
    "tags": ["internal", "game"]
  }
}

Response

OK

Success

status string required 
- “OK”
data object required 

Updated group data.
- id string required 
  
  Group ObjectID.
- project_id string required 
  
  ID of the project the group belongs to.
- title string required 
  
  Group title.
- tags array of strings optional 
  
  List of tags assigned to the group.

Response example

{
  "status": "OK",
  "data": {
    "id": "...",
    "project_id": "my_project",
    "title": "Test group",
    "tags": ["internal", "game"]
  }
}

ERROR

Error

status string required 
- “ERROR”
error string required 

Descriptive error message.

Response example

{
  "status": "ERROR",
  "error": "group not found"
}

Save Group Access Settings

Updates the group’s users and conditions fields. The condition object supports the same filter types as role conditions: domain, uid, tag, purchase, everyone, and logical operators and, or. Note that ip conditions are not allowed in group conditions.

Access Requirements

The request author must have a positive projectID/groups/<groupID>/group.can_manage_group rule.

Note

The maximum number of users per group is 100.

Request

POST /api/permissions/group/access

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

jwt string required 

User’s JWT token.
factor string conditionally required 

User device factor. Required if service_jwt is not provided.
service_jwt string conditionally required 

Service JWT. Required if factor is not provided.
group_id string required 

Group ObjectID.
data object required 
- conditions array of objects optional 
  
  List of conditions for automatic group membership.
  - title string required 
    
    Condition name for display purposes.
  - condition object required 
    
    Filter expression. Supports the same filter types as role conditions, except ip.
- users array of strings optional 
  
  List of explicitly added user IDs.

Request example

POST /api/permissions/group/access

Headers

Authorization: Bearer eyJhbGci...
Factor: ...

Body

{
  "group_id": "<objectID>",
  "data": {
    "conditions": [
      {
        "title": "Internal users",
        "condition": {"domain": "example.com"}
      }
    ],
    "users": ["uid1", "uid2"]
  }
}

Response

OK

Success

status string required 
- “OK”
data object required 

Updated group data.
- id string required 
  
  Group ObjectID.
- project_id string required 
  
  ID of the project the group belongs to.
- title string required 
  
  Group title.
- conditions array of objects optional 
  
  List of conditions for automatic group membership.
- users array of strings optional 
  
  List of explicitly added user IDs.

Response example

{
  "status": "OK",
  "data": {
    "id": "...",
    "project_id": "my_project",
    "title": "Test group",
    "conditions": [
      {
        "title": "Internal users",
        "condition": {"domain": "example.com"}
      }
    ],
    "users": ["uid1", "uid2"]
  }
}

ERROR

Error

status string required 
- “ERROR”
error string required 

Descriptive error message.

Response example

{
  "status": "ERROR",
  "error": "group not found"
}