Groups API

Use the Groups API to add, edit, list, and delete groups in EASE. Groups are the connection between individual users and applications. In order for a user to view and run an application, the user must be a member of the group to which the application belongs.

You can create groups to organize user access to applications. For example, you may want to create groups for different functional areas within your organization since employees in each of those areas will have different application needs.

The system has one default group called “All Users.” You cannot delete or change the name of the All Users group.

The Groups API lets you:

  • List all groups
  • Add, update, or delete a group
  • Add a user to multiple groups
  • Add multiple users to one group
  • Remove multiple users from a group
  • List all applications in a group
  • Add to and delete applications from a group

Resources

GET /v1/groups/

List All Groups

Must be authenticated as an EASE administrator.

Returns a list of all the groups for the authenticated user’s organization. This list includes the number of users and number of applications belonging to each group.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/
Europe https://eu01ws.apperian.eu/v1/groups/

URL Parameters

None

Data Parameters

None

Example Request

curl -X GET https://na01ws.apperian.com/v1/groups/ --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Example Response

{
  "groups": [
     {
       "app_count": 74, 
       "psk": 3071, 
       "user_count": 36, 
       "name": "All Users", 
       "description": "All Users in system (default group)"
     }, 
     {
       "app_count": 1, 
       "psk": 3634, 
       "user_count": 6, 
       "name": "Boston", 
       "description": "Boston Employees"
     }, 
     {
       "app_count": 0, 
       "psk": 3635, 
       "user_count": 5, 
       "name": "Engineering", 
       "description": "Engineering Team"
     }, 
     {
       "app_count": 6, 
       "psk": 5326, 
       "user_count": 3, 
       "name": "Customer Support", 
       "description": "Worldwide Customer Support Organization"
     }, 
     {
       "app_count": 0, 
       "psk": 5775, 
       "user_count": 1, 
       "name": "QA Workflow", 
       "description": "Quality assurance engineering"
     }, 
     {
       "app_count": 0, 
       "psk": 6255, 
       "user_count": 4, 
       "name": "Valladolid", 
       "description": "Valladolid Office"
     }, 
     {
       "app_count": 0, 
       "psk": 6413, 
       "user_count": 3, 
       "name": "Paris Sales", 
       "description": "Paris Sales Office"
     }
    ]
  }
POST /v1/groups/

Add Group

Must be authenticated as an EASE administrator.

Adds a new group to the authenticated user’s organization.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/
Europe https://eu01ws.apperian.eu/v1/groups/

URL Parameters

None

Data Parameters

group_name
(Required) Name for the group. Maximum characters: 50
group_description
(Required) Description for the group that will appear in the list of groups on the Groups page in the EASE Portal. Maximum characters: 500

Example Request

curl -X POST https://na01ws.apperian.com/v1/groups/ --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"group_name": "Paris", "group_description": "Paris Office"}'

Example Response

{
  "group": {
    "psk": 6413, 
    "name": "Paris", 
    "description": "Paris Office"
  }
}
POST /v1/groups/users/(int: user_psk)

Add One User to Multiple Groups

Must be authenticated as an EASE administrator.

Adds a specified user to a list of groups. Specify groups by group_psk.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/users/<int:user_psk>
Europe https://eu01ws.apperian.eu/v1/groups/users/<int:user_psk>

URL Parameters

user_psk
(Required) Unique ID assigned by EASE to the user you want to add to the list of groups.

Data Parameters

group_psk
(Required) Comma-separated list of the group_psks for the groups to which you want to add the user.

Example Request

The following example adds user 21778 to groups 3635, 5775, and 6178.

curl -X POST https://na01ws.apperian.com/v1/groups/users/21778 --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"group_psk": [3635, 5775, 6178]}'

Example Response

{
  "added_groups": [
    3635, 
    5775, 
    6178
  ], 
  "failed_groups": []
}
GET /v1/groups/(int: group_psk)/applications/

List Applications in Group

Must be authenticated as an EASE administrator.

Returns a list of the applications that are in the specified group.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>/applications/
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>/applications/

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

None

Example Request

This example lists appliations in the group with the 123 group_psk.

curl -X GET https://na01ws.apperian.com/v1/groups/123/applications/ --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Example Response

There is one application in the group.

{
   "applications": [
     {
       "display_message": "", 
       "operating_system": 1, 
       "update_compliance_period_in_days": null, 
       "icon_path_114": "", 
       "url_scheme": "", 
       "form_factor": 3, 
       "long_description": "An Awesome App", 
       "allow_ota": true, 
       "is_adhoc": false, 
       "platform": null, 
       "is_hybrid": false, 
       "required_by": "3099-12-31T00:00:00+00:00", 
       "is_pairing_webapp": false, 
       "os_version": null, 
       "is_app_catalog": false, 
       "short_description": "An Awesome App", 
       "screenshot_path3": "", 
       "screenshot_path1": "", 
       "type": 0, 
       "screenshot_path4": "", 
       "screenshot_path5": "", 
       "status": 1, 
       "psk": 14080, 
       "icon_path_512": "", 
       "sort_weight": 1000, 
       "no_auth_delivery_enabled": false, 
       "deleted": null, 
       "icon_path": "org_1062/iphone_14080/icon_0ed5a151fbf5277494feff800d5a88c5.png", 
       "is_email_config_profile": false, 
       "screenshot_path2": "", 
       "tablet_screenshot_path5": "", 
       "min_os_version": "3.1", 
       "bundle_id": "com.apperian.app", 
       "tablet_screenshot_path3": "", 
       "icon_path_72": "", 
       "tablet_screenshot_path4": "", 
       "bundle_version": null, 
       "tablet_screenshot_path2": "", 
       "name": "App", 
       "tablet_screenshot_path1": "", 
       "upgrade_bundle_id": null, 
       "required": false, 
       "push_enabled": false, 
       "is_background_daemon": false, 
       "is_critical": false
     }
   ]
 }
POST /v1/groups/(int: group_psk)/applications/

Add Applications to Group

Must be authenticated as an EASE administrator.

Adds a comma-separated list of applications to a specified group. Specify apps by app_psk.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>/applications/
Europe https://eu01ws.apperian.eu/v1groups/<int:group_psk>/applications/

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

app_psk
(Required) Comma-separated list of the app_psks for the applications you want to add to the group.

Example Request

The following example adds apps 14203, 5714, and 14205 to group 123.

curl -X POST https://na01ws.apperian.com/v1/groups/123/applications/ --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"app_psk": [14203, 5714, 14205]}'

Example Response

{
  "apps_added": [
    14203, 
    5714, 
    14205
  ], 
  "apps_failed": []
}
DELETE /v1/groups/(int: group_psk)/applications/

Delete Applications from Group

Must be authenticated as an EASE administrator.

Removes a comma-separated list of applications from a group. Specify apps by app_psk.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>/applications/
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>/applications/

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

app_psk
(Required) Comma-separated list of the app_psks for the applications you want to remove from the group.

Example Request

The following example removes apps 14203, 5714, 14205 from group 576.

curl -X DELETE https://na01ws.apperian.com/v1/groups/576/applications/ --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"app_psk": [14203, 5714, 14205]}'

Example Response

{
  "apps_removed": [
    14203, 
    5714, 
    14205
   ], 
   "apps_failed": []
}
GET /v1/groups/(int: group_psk)/users/

List Users in Group

Must be authenticated as an EASE administrator.

Returns a list of users in a specified group.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>/users/
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>/users/

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

None

Example Request

curl -X GET https://na01ws.apperian.com/v1/groups/123/users/ --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Example Response

{
   "users_in_group": [
     {
       "psk": 21778, 
       "first_name": "Alexander", 
       "last_name": "Christopher", 
       "deleted": null, 
       "email": "achristopher@example.com", 
       "mobile_phone": "978-448-8637", 
       "role": 1, 
       "created_date": "2012-05-02T19:36:02+00:00", 
       "until_date": "9999-12-31T23:59:59.999999", 
       "disabled_reason": null, 
       "id": "achristopher@example.com", 
       "last_login_from_catalog": null
     }, 
     {
       "psk": 21781, 
       "first_name": "Melanie", 
       "last_name": "Boatwright", 
       "deleted": null, 
       "email": "mboatwright@example.com", 
       "mobile_phone": "978-448-8637", 
       "role": 1, 
       "created_date": "2012-05-02T19:36:02+00:00", 
       "until_date": "2013-11-18T14:38:26+00:00", 
       "disabled_reason": 0, 
       "id": "mboatwright@example.com", 
       "last_login_from_catalog": null
      } 
    ]
  }
POST /v1/groups/(int: group_psk)/users/

Add Multiple Users to Group

Must be authenticated as an EASE administrator.

Adds a list of users to a specified group. Specify users by user_psk.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>/users/
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>/users/

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

user_psk
(Required) Comma-separated list of the user_psks for the users you want to add to the group.

Example Request

The following example adds users with user_psks 103172, 26886, and 21778 to group 123.

curl -X POST https://na01ws.apperian.com/v1/groups/123/users/ --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"user_psk": [103172, 26886, 21778]}'

Example Response

{
  "users_failed": [], 
  "users_added": [
    103172, 
    26886, 
    21778
  ]
}
DELETE /v1/groups/(int: group_psk)/users/

Remove Users from Group

Must be authenticated as an EASE administrator.

Removes a comma-separated list of users from a group. Specify users by user_psk.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>/users/
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>/users/

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group from which you want to remove users.

Data Parameters

user_psk
(Required) Comma-separated list of the user_psks for the users you want to remove from the group.

Example Request

The following example removes user 21778 from group 3635. The command also attempts to remove user 103172, but that user is not in group 3635.

curl -X DELETE https://na01ws.apperian.com/v1/groups/3635/users/ --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"user_psk": [103172, 26886]}'

Example Response

{
  "users_failed": [
    {
      "object_id": 103172, 
      "error": {
         "code": 20, 
         "message": "User 103172 is not in the group 3635", 
         "guid": "2bbcb3f0-7fe4-4aac-ac09-1673e578a8de", 
         "error_details": null
       }
     }
   ], 
   "users_removed": [
     21778
   ]
 }
PUT /v1/groups/(int: group_psk)

Update Group

Must be authenticated as an EASE administrator.

Updates data for an existing group in the authenticated user’s organization.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

group_name
(Required) Updated name for the group. Maximum characters: 50
group_description
(Required) Updated description for the group. Maximum characters: 500

Example Request

curl -X PUT https://na01ws.apperian.com/v1/groups/6413 --header "Content-Type: application/json" --header "X-TOKEN: hShU5OD-SiadD8gyC_K4HA" --data '{"group_name": "Paris Sales", "group_description": "Paris Sales Office"}'

Example Response

{
  "group": {
     "psk": 6413, 
     "name": "Paris Sales", 
     "description": "Paris Sales Office"
  }
}
DELETE /v1/groups/(int: group_psk)

Delete Group

Must be authenticated as an EASE administrator.

Permanently deletes a group from the authenticated user’s organization. Before deleting a group, consider the impact it will have on members of that group. They will no longer be able to access applications they were authorized to use based on membership to that group.

You cannot delete the “All Users” group; it is the system’s default group.

Resource URL

Environment URL
North America https://na01ws.apperian.com/v1/groups/<int:group_psk>
Europe https://eu01ws.apperian.eu/v1/groups/<int:group_psk>

URL Parameters

group_psk
(Required) Unique ID assigned by EASE to the group.

Data Parameters

None

Example Request

The following example deletes group 123.

curl -X DELETE https://na01ws.apperian.com/v1/groups/123 --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Example Response

{
  "deleted_group": {
    "psk": 123, 
    "name": "Green Team", 
    "description": "Office Green Team Project"
  }
}

Table Of Contents