- 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&queryOperator=OR
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 |
Type |
includeTotal |
query |
If you want the total number of groups included in the response (which may be different from
the number of groups 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 groups 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 groups to exclude from the beginning of the list of groups 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 groups, specify
max=50 (and optionally offset=0 ); and to get the next 50 matching groups specify
max=50 and offset=50 , and so on. |
int |
query |
query |
(Optional) A query for filtering the group results.
Fields name, profileGuid, userGuid, appConfigGuid and userEcoid 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 starts 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.
For fields that support contains matching, the value should be wrapped up using (*) symbols.
For example, to find users that have a display name that contains "user" value, specify
name=*group* .
To match an asterisk in the beginning and at the end of a string instead of contains matching, the asterisks
must be escaped with a backslash. For example: name=\*group\* .
To use prefix matching instead of contains for the string that start with asterisk symbol, the following pattern
should be used: name=\*group* .
The following table describes the fields that can be used in the query.
Field |
Type |
Description |
Supports prefix matching |
Supports contains matching |
appConfigGuid |
string |
Specify this to get groups that have applications with this configuration assigned to them. |
No |
No |
name |
string |
Name of the group. |
Yes |
Yes |
profileGuid |
string |
Specify this to get groups that have this profile assigned to them. |
No |
No |
userEcoid |
string |
Specify this to get groups that have this user assigned to them. |
No |
No |
userGuid |
string |
Specify this to get groups that have this user assigned to them. |
No |
No |
|
|
queryOperator |
query |
The field to specify the query operator.
Operator |
Description |
AND |
The 'AND' logic will be applied to all fields that are specified in the query. The operator is used by
default even if 'queryOperator' parameter is not defined in the query |
OR |
The 'OR' logic will be applied to all fields that are specified in the query |
|
|
sortBy |
query |
The field to sort the group results by. The format is <field name> ASC|DESC , where
ASC means to sort the results in ascending order and DESC means descending order. For
example, to sort the results by group name in descending order, specify name DESC . If not
specified, a value of name ASC will be used. The following fields are allowed: name. |
|
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) |
|
GET /{tenantGuid}/api/v1/groups/{groupGuid}/applications
- Available Since:
- 12.13.0
Get the apps or app groups that were directly or indirectly assigned to a group.
Samples
Sample 1 request
Get all apps and app groups assigned directly or indirectly to a group.
GET /SRP00000/api/v1/groups/2d2d3a7f-076d-46f9-8c25-56cb8eba2800/applications
Sample response body
{
"applicationAssignments" : [ {
"application" : {
"guid" : "aa291d31-3b51-4424-a09c-7b127ee398a8",
"name":"sampleApplication",
"description" : "Our sample app.",
"os": "android",
"packageId": "com.sample.app.client",
"sourceName": "In Store",
"storeName": "Google Play",
"securedType": "All Android devices",
"reviewMode": "PUBLIC"
},
"applicationConfig" : {
"appGuid": "aa291d31-3b51-4424-a09c-7b127ee398a8",
"appName": "sampleApplication",
"appPackageId": "com.sample.app.client",
"guid": "d5b1b6bd-deec-4196-898d-9c0e68925385",
"name": "Sample App Configuration",
"rank": 0
},
"disposition" : "OPTIONAL",
"assignment" : "DIRECT"
},
{
"applicationGroup" : {
"guid" : "4e9e07fd-f2f9-4eea-94eb-85524dcecb9e",
"name" : "Business apps",
"description" : "App group for Internal marketing department"
},
"disposition" : "REQUIRED",
"assignment" : "DIRECT"
},
{
"applicationGroup" : {
"guid" : "5e9e07fd-f2f9-5eea-95eb-85525dcecb9f",
"name" : "Business apps",
"description" : "App group for Finance department"
},
"disposition" : "REQUIRED",
"assignment" : "INDIRECT",
"links" : [ {
"rel" : "group",
"href" : "https://server01:18084/SRP00000/api/v1/group/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
} ]
}
Sample 2 request
Get all apps and app groups assigned a group through indirect assignment.
GET /SRP00000/api/v1/groups/2d2d3a7f-076d-46f9-8c25-56cb8eba2800/applications?query=assignment=INDIRECT
Sample 2 response body
{
"applicationAssignments" : [ {
"application" : {
"guid" : "aa291d31-3b51-4424-a09c-7b127ee398a8",
"name":"sampleApplication",
"description" : "Our sample app.",
"os": "android",
"packageId": "com.sample.app.client",
"sourceName": "In Store",
"storeName": "Google Play",
"securedType": "All Android devices",
"reviewMode": "PUBLIC"
},
"applicationConfig" : {
"appGuid": "aa291d31-3b51-4424-a09c-7b127ee398a8",
"appName": "sampleApplication",
"appPackageId": "com.sample.app.client",
"guid": "d5b1b6bd-deec-4196-898d-9c0e68925385",
"name": "Sample App Configuration",
"rank": 0
},
"disposition" : "OPTIONAL",
"assignment" : "INDIRECT",
"links" : [ {
"rel" : "group",
"href" : "https://server01:18084/SRP00000/api/v1/groups/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
} ]
},
{
"applicationGroup" : {
"guid" : "4e9e07fd-f2f9-4eea-94eb-85524dcecb9e",
"name" : "Business apps",
"description" : "App group for Internal marketing department"
},
"disposition" : "REQUIRED",
"assignment" : "INDIRECT",
"links" : [ {
"rel" : "group",
"href" : "https://server01:18084/SRP00000/api/v1/groups/2d2d3a7f-076d-46f9-8c25-56cb8eba2800"
} ]
}
Request Parameters
Name |
Location |
Description |
groupGuid |
path |
GUID of the group to get assigned applications for |
query |
query |
A query for filtering the application assignment results. The format is
<field name>=<query value> ,
for example assignment=DIRECT to return only directly assigned applications and application groups.
Multiple field-value pairs can be provided in the query with each pair separated with a comma, in which case
only applications matching all of the criteria provided will be included in the response. Querying for
empty/null
values is not supported.
Field |
Type |
Description |
assignment |
string |
Specify "direct" or "indirect" to return applications assigned by the specified assignment type. Multiple
assignment types can be separated with a semicolon, for example assignment=direct;indirect to
return applications and app groups assigned directly and indirectly. |
|
Response Codes
Code |
Condition |
Data type |
200 |
OK. |
|
400 |
Invalid search query. |
|
404 |
Group not found. |
|
Response Body
Media type |
Data type |
Description |
application/vnd.blackberry.applicationassignments-v1+json |
Application assignments
(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. |
|