Introduction
This article explains how to manage your groups, including creation and deletion.
App47 APIv2 Groups
Overview
The group end point allows you create, update, list, view and delete groups in your account. You must have the proper permissions in your account in order to use this end point with your member token.
To use this API you must have the following permissions
| Action | Required permission |
|---|---|
| List groups | At least read permission |
| Show group | At least read permission |
| Edit group | At least edit permission |
| Create group | Manage permission |
| Delete group | Manage permission |
For more information on how to configure your APIv2 calls, please consult the APIv2 Overview.
Parameters of a Group
When fetching, creating or updating information about groups, the flow parameters are available through the API:
| Parameter Name | Input | Output | Description |
|---|---|---|---|
| name | Yes | Yes | Name of the group |
| description | Yes | Yes | Description of the group |
| self_registration_enabled | Yes | Yes | Boolean value indicating if self user registration is enabled for this group. |
| enrolled_user_autoapprove | Yes | Yes | If users registered via the self user registration should be auto approved or require approval by a User administrator first. |
| session_hours_lenth | Yes | Yes | For SSO Enabled groups, how long the App Store session may last before requiring authentication. |
How to List Groups
Groups in your account can be viewed in a list if you have at least read access. You will need to use a call as described below:
End Point
GET https://cirrus.app47.com/api/v2/groups
Example:
curl -H"Access-Token: <<your token>>" https://cirrus.app47.com/api/v2/groups
Input Parameters
| Parameter | Description | Required? | Example(s)/Allowed Values |
|---|---|---|---|
| search_term | Search phrase to filter the group list | No | Any text |
| skip | The number of records to skip over | No | Integer greater than zero |
Example, to list only groups with the name or email “Test” in them:
curl -H"Access-Token: <<your token>>" https://webui.app47.net/api/v2/groups?search_term=Test
Expected Output
If valid, it will return a result with:
-
Success set to true
-
Skip - the number of records that were skipped (The API will return sets of 100 records)
-
Total - The total number of records in your account
-
Count - The total number of records returned in this response
-
List - List of groupss you have access to and match the input parameters
-
A md5 hash of the "results" element
-
HTTP result code 200
{
"results":
{
"skip": 0,
"total": 0,
"count": 0,
"list": [],
"success":true
},
"md5":"896d94e5e2f4eb6b6bfa19144c7794e5"
}
If invalid, it will return a result with:
-
Success set to false
-
A message indicating the error
-
A md5 has of the "results" element
-
HTTP result code that is *not* 200
{
"results":
{
"message":"Access denied",
"success":false
},
"md5":"896d94e5e2f4eb6b6bfa19144c7794e5"
}
How to Show a Specific Group
You can also show a specific group in your account by group ID. The group ID can be found on the previous call to list all groups. To show that group, you will then need to use a call as described below:
End Point
GET https://cirrus.app47.com/api/v2/groups/«group_id»
Example:
curl -H"Access-Token: <<your token>>" https://cirrus.app47.com/api/v2/groups/<< group_id >>
Input Parameters
| Parameter | Description | Required? | Example(s)/Allowed Values |
|---|---|---|---|
| group_id | The ID of the group | Yes | A valid group id in your account that you have permission to view |
Expected Output
{
"results":
{
"group":
{
"id":"544fa14538d6b81f6b00003d",
"created":"2014-10-28T13:59:34Z",
"modified":"2015-08-03T15:43:35Z",
"name":"Test",
"description":"Test Group",
"self_registration_enabled":true,
"enrolled_user_autoapprove":true,
"session_hours_length":24
},
"success":true
},
"md5":"7232f70a2678e2b4ba959fd853488ab1"
}
How to Update a Group
Update a specific group in your account by group ID. The group ID can be found on the call to list all groups.
Parameters that are allowed during update can be found in the table above where the Input column contains a Yes.
You will need to use a call as described below:
End Point
PUT https://cirrus.app47.com/api/v2/groups/«group_id»
Example:
curl -X PUT -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"group": { "name": "Updated Name" } }' https://cirrus.app47.com/api/v2/group/<< group_id >>
Expected Output
{
"results":
{
"group":
{
"id":"544fa14538d6b81f6b00003d",
"created":"2014-10-28T13:59:34Z",
"modified":"2015-08-03T15:43:35Z",
"name":"Updated Name",
"description":"Test Group",
"self_registration_enabled":true,
"enrolled_user_autoapprove":true,
"session_hours_length":24
},
"success":true
},
"md5":"7232f70a2678e2b4ba959fd853488ab1"
}
Create a Group
You may only create group if your member has the permission to manage groups.
Parameters that are allowed during creation can be found in the table above where the “Input” column contains a “Yes” in the row.
You will need to use a call as described below:
End Point
POST https://cirrus.app47.com/api/v2/groups
Example:
curl -X POST -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"group": { "name": "New Name" } }' https://cirrus.app47.com/api/v2/groups
Expected Output
{
"results":
{
"group":
{
"id":"544fa14538d6b81f6b00003d",
"created":"2014-10-28T13:59:34Z",
"modified":"2015-08-03T15:43:35Z",
"name":"New Name",
"description":nil,
"self_registration_enabled":true,
"enrolled_user_autoapprove":true,
"session_hours_length":24
},
"success":true
},
"md5":"7232f70a2678e2b4ba959fd853488ab1"
}
Delete a Group
You may only delete groups if you have permission to manage groups.
End Point
DELETE https://cirrus.app47.com/api/v2/groups/«group_id»
Example:
curl -X DELETE -H"Access-Token: <<your token>>" https://cirrus.app47.com/api/v2/groups/<<group_id>>
Expected Output
{
"results":
{
"message":"Group was deleted",
"success":true
},
"md5":"f3d0a22e47ce6158551f483e07b16fe1"
}
Group Associations
Groups are associated with apps and users, which can be manipulated through the group end point.
Users Associated With a Group
End Point
GET https://cirrus.app47.com/api/v2/groups/<<group_id>>/users
Note: By default, a call to the above URL will return a maximum of 100 users, starting with the first user in the list. To change either of these, add one of the following to the end of the url:
- limit=[new_limit]
- skip=[the_number_of_users_to_skip]
Both parameters can also be used together:
GET https://cirrus.app47.com/api/v2/groups/<<group_id>>/users?limit=3,skip=1
In the url above, the returned result would skip the first user in the group, and show a maximum of 3 other users.
Example:
curl -H"Access-Token: <<your token>>" https://cirrus.app47.com/api/v2/groups/<<group_id>>/users
Expected Output
{
"results":
{
"skip": 0,
"total": 1,
"count": 1,
"list":
[{
"id":"544fa14538d6b81f6b00003d",
"created":"2014-10-28T13:59:34Z",
"modified":"2015-08-03T15:43:35Z",
"name":"New Name",
"email":"new@name.com"
}],
"success":true
},
"md5":"7232f70a2678e2b4ba959fd853488ab1"
}
Add a User to a Group
End Point
PUT https://cirrus.app47.com/api/v2/groups/<<group_id>>/users/<<user_id>>
Example:
curl -X PUT --H"Access-Token: <<your token>>" https://cirrus.app47.com/api/v2/groups/<<group_id>>/users/<<user_id>>
Expected Output
{
"results":
{
"related": true,
"success":true
},
"md5":"7232f70a2678e2b4ba959fd853488ab1"
}
Comments
0 comments
Please sign in to leave a comment.