- Home
- Resources
- Groups
Provides access and management of groups.
GET /{tenantGuid}/api/v1/groups
- Available Since:
- 12.6.0
Get user groups with a specific query or all user groups.
If no groups are found, an empty group list is included in the response body.
Sample request
GET /SRP00000/api/v1/groups?query=profileGuid=3d55abd2-c00e-4f5f-abcf-01c92ac777b1,userGuid=6dd3a8e2-3f24-48c6-961a-949794f4b554
Sample response body
{
"groups" : [ {
"guid" : "6d0c4ddb-10ae-471d-948d-df27868dcf8a",
"name" : "Test group name",
"description" : "Test group description",
"directoryLinked" : false
} ]
}
Request Parameters
Name |
Location |
Description |
query |
query |
(Optional) A query for filtering the group results. The name field cannot be used with other fields.
The profileGuid and userGuid field can be combined separated by a comma to narrow the results. Special
characters (comma, backslash) in query values must be escaped with a backslash.
By default, a case-insensitive exact match will be performed for each field in the query. For fields that
support prefix (i.e. starts with) matching, append an asterisk ("*") to the end of the value. For example, to
find groups that have a name that start with "M", specify name=m* . To match an asterisk at
the end of a string instead of prefix matching, the asterisk must be escaped with a backslash.
The following table describes the fields that can be used in the query.
Field |
Type |
Description |
Supports prefix matching |
name |
string |
Name of the group. |
Yes |
profileGuid |
string |
Specify this to get groups that have this profile assigned to them. |
No |
userGuid |
string |
Specify this to get groups that have this user assigned to them. |
No |
|
Response Codes
Code |
Condition |
Data type |
200 |
OK (even if no groups are found). |
|
400 |
Invalid search query. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.groups-v1+json |
Groups
(JSON) |
|
POST /{tenantGuid}/api/v1/groups
- Available Since:
- 12.7.0
Create a user group. Only the name field of the group is required. The description field is optional.
Samples
Sample request body
{
"name":"Test group name",
"description":"Test group description"
}
Sample response body
{
"guid":"6d0c4ddb-10ae-471d-948d-df27868dcf8a",
"name":"Test group name",
"description":"Test group description",
"directoryLinked":false
}
Request Body
Media type |
Data type |
application/vnd.blackberry.group-v1+json |
Group
(JSON) |
Response Codes
Code |
Condition |
Data type |
201 |
Group created. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
409 |
Group already exists. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.group-v1+json |
Group
(JSON) |
|
Response Headers
Name |
Description |
|
|
DELETE /{tenantGuid}/api/v1/groups/{groupGuid}
- Available Since:
- 12.7.0
Delete a user group.
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the user group to delete. |
Response Codes
Code |
Condition |
Data type |
204 |
Group deleted. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found. |
|
GET /{tenantGuid}/api/v1/groups/{groupGuid}
- Available Since:
- 12.6.0
Get user group by a specific GUID.
Sample response body
{
"guid":"6d0c4ddb-10ae-471d-948d-df27868dcf8a",
"name":"Test group name",
"description":"Test group description",
"directoryLinked":false
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to get |
Response Codes
Code |
Condition |
Data type |
200 |
OK. |
|
404 |
Group not found. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.group-v1+json |
Group
(JSON) |
|
POST /{tenantGuid}/api/v1/groups/{groupGuid}/applications
- Available Since:
- 12.7.0
Assign one or more applications or application groups, by GUID, to a user group. If the application or application group is
already assigned, the disposition and application config will be updated. Only the GUID field of each application,
application config or application group is required along with disposition. NOTE: The "DENIED" disposition is not supported
for application groups. Application config property is optional. Only application config GUID is required to define an
app config. NOTE: Application config cannot be assigned to application group. NOTE: Only BlackBerry Dynamics app configs
are supported.
Sample request body
{
"applicationAssignments" : [ {
"application" : {
"guid" : "aa291d31-3b51-4424-a09c-7b127ee398a8"
},
"disposition" : "OPTIONAL"
}, {
"application" : {
"guid" : "841e0146-07d5-4963-947c-dcabe7293806"
},
"disposition" : "REQUIRED"
}, {
"applicationGroup" : {
"guid" : "6d0c4ddb-10ae-471d-948d-df27868dcf8a"
},
"disposition" : "OPTIONAL"
} ]
}
Sample request body with application config defined
{
"applicationAssignments": [{
"application": {
"guid": "ef7fb3f4-5ed5-4f53-b54d-c0280cbf2716"
},
"disposition": "OPTIONAL",
"applicationConfig": {
"guid": "A2BA5128-FE07-4DF9-AE09-5FC31F4C774E"
}
},
{
"application": {
"guid": "c2cff83f-bbe0-4903-b2e9-557278656fe9"
},
"disposition": "OPTIONAL",
"applicationConfig": {
"guid": "0651D265-069D-4B79-94C3-B1326B70E130"
}
}
]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to assign applications to. |
Request Body
Media type |
Data type |
application/vnd.blackberry.applicationassignments-v1+json |
Application assignments
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
Applications(s) assigned. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Application not found.Group not found.Application group not found. |
|
DELETE /{tenantGuid}/api/v1/groups/{groupGuid}/applications/{appGuid}
- Available Since:
- 12.7.0
Unassign an application, by GUID, from a user group.
Request Parameters
Name |
Location |
Description |
appGuid |
path |
GUID of the application to unassign. |
groupGuid |
path |
GUID of the group to unassign the application from. |
Response Codes
Code |
Condition |
Data type |
204 |
Application unassigned. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Application not found.Group not found. |
|
DELETE /{tenantGuid}/api/v1/groups/{groupGuid}/groups
- Available Since:
- 12.12.0
Remove one or more child groups from a parent group. If a child group listed in the request is not assigned to a parent
group, it is ignored. If a child group listed in the request can’t be removed, the entire request is not processed, and an
error message is returned.
Sample request
DELETE /SRP00000/api/v1/groups/b7030076-cfb9-43e6-a88c-355b190c1291/groups
Sample request body
{
"groups": [{
"guid": "953a2988-6d25-4399-b40f-477f44c3a482"
},{
"guid": "25311b56-b8a6-41d1-aa37-2d56ebebe524"
}]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
|
Request Body
Media type |
Data type |
application/vnd.blackberry.groups-v1+json |
Groups
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
OK. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found. |
|
Response Body
Media type |
Data type |
Description |
application/json |
Groups
(JSON) |
|
GET /{tenantGuid}/api/v1/groups/{groupGuid}/groups
- Available Since:
- 12.12.0
Get child user groups by a specific parent user group GUID.
If no child groups are found, an empty group list is included in the response body.
Sample request
GET /SRP00000/api/v1/groups/b7030076-cfb9-43e6-a88c-355b190c1291/groups
Sample response body
{
"groupAssignments": [{
"group": {
"guid": "953a2988-6d25-4399-b40f-477f44c3a482",
"name": "Child group 1",
"description": "Child group description 1",
"directoryLinked": false
},
"indirect": false
},{
"group": {
"guid": "25311b56-b8a6-41d1-aa37-2d56ebebe524",
"name": "Child group 2",
"description": "Child group description 2",
"directoryLinked": false
},
"indirect": false
},{
"group": {
"guid": "29d8313e-1ea8-40df-a0f9-214f0a48ff1e",
"name": "Child group 3",
"description": "Child group description 3",
"directoryLinked": false
},
"indirect": true
}]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
|
Response Codes
Code |
Condition |
Data type |
200 |
OK. |
|
404 |
Group not found. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.groupassignments-v1+json |
Group assignments
(JSON) |
|
POST /{tenantGuid}/api/v1/groups/{groupGuid}/groups
- Available Since:
- 12.12.0
Assign one or more child groups to a group. If a group listed in the request is already assigned to the parent group, it is
ignored. If one of the groups listed in the request can’t be assigned to the parent group, the entire batch is not added,
and an error message is returned.
Sample request
POST /SRP00000/api/v1/groups/b7030076-cfb9-43e6-a88c-355b190c1291/groups
Sample request body
{
"groups": [{
"guid": "953a2988-6d25-4399-b40f-477f44c3a482"
},{
"guid": "25311b56-b8a6-41d1-aa37-2d56ebebe524"
}]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
|
Request Body
Media type |
Data type |
application/vnd.blackberry.groups-v1+json |
Groups
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
OK. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found. |
|
409 |
Invalid request. For example, invalid field semantics or missing required field. Or possible incorrect groups nesting like attempt to add All Users group as child or make circular dependency. |
|
Response Body
Media type |
Data type |
Description |
application/json |
Groups
(JSON) |
|
GET /{tenantGuid}/api/v1/groups/{groupGuid}/profiles
- Available Since:
- 12.6.0
Get all profiles directly assigned to a user group.
Sample response body
{
"profiles" : [ {
"guid" : "3d55abd2-c00e-4f5f-abcf-01c92ac777b1",
"name" : "Sample Policy",
"categoryName" : "IT_CONFIG",
"default" : false
}, {
"guid" : "6106fce8-83f5-44b3-8288-e8e4e0966561",
"name" : "Default Email Profile",
"categoryName" : "EMAIL",
"default" : false
} ]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to get assigned profiles for |
Response Codes
Code |
Condition |
Data type |
200 |
OK. |
|
404 |
Group not found. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.profiles-v1+json |
Profiles
(JSON) |
|
POST /{tenantGuid}/api/v1/groups/{groupGuid}/profiles
- Available Since:
- 12.6.0
Assign one or more profiles, by GUID, to a user group. Only the GUID field of each profile is required.
Sample request body
{
"profiles" : [ {
"guid" : "3d55abd2-c00e-4f5f-abcf-01c92ac777b1"
}, {
"guid" : "6106fce8-83f5-44b3-8288-e8e4e0966561"
} ]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to assign profiles to. |
Request Body
Media type |
Data type |
application/vnd.blackberry.profiles-v1+json |
Profiles
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
Profile(s) assigned. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found. |
|
PUT /{tenantGuid}/api/v1/groups/{groupGuid}/profiles
- Available Since:
- 12.6.0
Replace all profiles assigned to a user group. All existing profiles are removed and replaced by the list of profiles (by
GUID) provided. Only the GUID field of each profile is required.
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to replace profiles for. |
Request Body
Media type |
Data type |
application/vnd.blackberry.profiles-v1+json |
Profiles
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
Profile(s) assigned. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found. |
|
DELETE /{tenantGuid}/api/v1/groups/{groupGuid}/users
- Available Since:
- 12.7.0
Remove one or more users, by GUID, from a user group. Only the GUID field of each user is required. Removing users from a
directory linked group is not supported.
Sample request body
{
"users" : [ {
"guid" : "6dd3a8e2-3f24-48c6-961a-949794f4b554"
}, {
"guid" : "f712cbb0-a36e-4f22-8a1a-f1c0fae6db97"
} ]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to remove users from. |
Request Body
Media type |
Data type |
application/vnd.blackberry.users-v1+json |
Users
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
User(s) removed. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found.User not found. |
|
GET /{tenantGuid}/api/v1/groups/{groupGuid}/users
- Available Since:
- 12.11.0
Get users assigned to a user group, sorted by username in ascending order.
Samples
Sample 1 request
Get the first 100 users.
GET /SRP00000/api/v1/groups/6862acf1-5d1e-4d7b-ad63-cda6c4df227E/users
Sample 1 response body
{
"users": [
{
"username": "pmorley",
"emailAddress": "pmorley@example.com",
"guid": "63b8c0fe-5930-4172-b107-8e34e1d4abee"
},
{
"username": "jromphf",
"emailAddress": "jromphf@example.com",
"guid": "6acca88d-e0a5-4182-b094-ed64bb671ef8"
}
]
}
Sample 2 request
Get the last 20 users with offset equals to 40 including a total users count.
GET /SRP00000/api/v1/groups/b7030076-cfb9-43e6-a88c-355b190c1291/users?max=20&offset=40&includeTotal=true
Sample 2 response body
{
"users": [
{
"username": "pmorley",
"emailAddress": "pmorley@example.com",
"guid": "3fec7917-65cc-4695-9d0f-fe4585f822cc"
}
],
"total": 41
}
Request Parameters
Name |
Location |
Description |
Type |
groupGuid |
path |
GUID of the group that you are querying for user membership. |
|
includeTotal |
query |
If you want the total number of users assigned to a group included in the response (which may be different from
the number of users returned) set this to true; otherwise set to false. By default the total will not be
included in the response. |
boolean |
max |
query |
The maximum number of user results to get, between 1 and 1000 inclusive. If not specified, a value of 100 will
be used. |
int |
offset |
query |
The number of matching users to exclude from the beginning of the list of users in the response; greater than or
equal to 0. If not specified, a value of 0 will be used to indicate that no matches should be excluded. Used in
order to get "pages" of results. For example, to get the first 50 matching users, specify max=50
(and optionally offset=0 ); and to get the next 50 matching users specify max=50 and
offset=50 , and so on. |
int |
Response Codes
Code |
Condition |
Data type |
200 |
OK. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.users-v1+json |
Users
(JSON) |
|
POST /{tenantGuid}/api/v1/groups/{groupGuid}/users
- Available Since:
- 12.7.0
Add one or more users, by GUID, to a user group. Only the GUID field of each user is required. Adding users to a directory
linked group is not supported.
Sample request body
{
"users" : [ {
"guid" : "6dd3a8e2-3f24-48c6-961a-949794f4b554"
}, {
"guid" : "f712cbb0-a36e-4f22-8a1a-f1c0fae6db97"
} ]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to add users to. |
Request Body
Media type |
Data type |
application/vnd.blackberry.users-v1+json |
Users
(JSON) |
Response Codes
Code |
Condition |
Data type |
204 |
User(s) added. |
|
400 |
Invalid request. For example, invalid field semantics or missing required field. |
|
404 |
Group not found.User not found. |
|