Managing groups via REST APIs

You can programmatically manage groups via REST APIs.

For all API calls related to group management, use type=group.

Creating a group

While creating a group or renaming an existing group, use action=createupdate.

POST https://portal.bitglass.com/api/bitglassapi/config/v1.1/?type=group&action=createupdate

Parameter Value Description Notes
groupname string Name of the user group required
newgroupname string New name of the user group required 
{
    "groupname": "sales"
}

While renaming an existing group:

  • Must pass the groupname and the newgroupname as parameters
  • If the groupname does not exist, will return an error to the user
    {
    "groupname": "sales",
    "newgroupname": "Sales Department"
}

Deleting group

While deleting the group, use action=delete.

POST https://portal.bitglass.com/api/bitglassapi/config/v1.1/?type=group&action=delete

Parameter Value Description Notes
groupname string Name of the user group required 
{
    "groupname": "sales"
}

Adding members to group

Adds the listed members to an existing user group. Listed members must already exist in Forcepoint ONE SSE with active accounts. While adding members to the group, use action=addmembers.

POST https://portal.bitglass.com/api/bitglassapi/config/v1.1/?type=group&action=addmembers

Parameter Value Description Notes
groupname string Name of the user group required
companyemail list Emails of the users that belong to the particular group required 
{
    "groupname": "sales",
    "companyemail": [
        "akholi@bitglass.com",
        "alinde@bitglass.com",
        "jdoherty@bitglass.com"
    ]
}
Note:
  • If all users listed in the request are non existent, a 400 response will be returned.
  • If some users in the request are nonexistent, a 200 response with be returned with the following message:
    Users: <useremails-added-to-group-separated-by-commas> have been added to group <group-name>.
Users <useremails-not-added-to-group-separated-by-commas> do not exist.

Removing members from group

Removes the listed members from an existing user group. Listed members must already exist in Forcepoint ONE SSE with active accounts. While removing members from the group, use action=removemembers.

POST https://portal.bitglass.com/api/bitglassapi/config/v1.1/?type=group&action=removemembers

Parameter Value Description Notes
groupname string Name of the user group required
companyemail list Emails of the users that belong to the particular group required
Note:
  • If all users listed in the request are non existent, a 400 response will be returned with the following message:
    Users <useremails-separated-by-commas> do not exist.
  • If some users in the request are nonexistent, a 200 response with be returned with the following message:
    Users: <useremails-separated-by-commas> have been removed to group <group-name>. 
Users <useremails-not-removed-from-group-separated-by-commas> do not exist.

Viewing List of Groups

Use the following API to get an array of groups in the tenant:

GET https://portal.bitglass.com/api/bitglassapi/config/v2/group/

Note: The default group which contains all users is named as All Users.
{
   "response":{
      "dataformat":"json",
      "groups":[
         "Bitglass Admins",
         "amiya-only",
         "All Users"
      ],
   }
}

Viewing details of single group

Use the following API to view the basic details of group members (next_page_token, last_page_token, Username, first Name, Last Name and status) and group's admin role of single group:

GET https://portal.bitglass.com/api/bitglassapi/config/v2/group/<group_name>/user_status/<status>?page_size=<page_size>&page_token=<page_token>

Parameter Value Description Notes
groupname string Name of the user group required
status string Status of that particular group. If status is not defined, then active is selected by default. Possible values for status are active, confirm_deactivate and deactivated. required
page_size integer No of items to be included in a page. This field is defaulted to 25 and can be maximum 100. optional
page_token string Can be either the next_page_token or last_page_token from the response. optional 
{
   "next_page_token":"NXRoaXNfaXNfYV9wYWdlX3Rva2Vu",
   "last_page_token":"NXRoaXNfaXNfYV9wYWdlX3Rva2Vu"
   "response":{
      "dataformat":"json",
      "groupname":"Bitglass Admins",
      "adminrole":"System Administrator",
      "total_users_count": 1000,
      "users":[
         {
            "username":"asingh@acme-gadget.com",
            "firstname":"Amit",
            "lastname":"Singh",
            "status":"Admin Role Conflict",
            "risk_score":"3"
         },
         {
            "username":"adas@acme-gadget.com",
            "firstname":"Amiya",
            "lastname":"Das",
            "status":"Deactivated",
            "risk_score":"3"
         }
      ],
   }
}