Groups Resource

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
Location Location of the created group. Can be used to perform a GET request to retrieve the group. Only present when status is 201.

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.