Getting started

The BlackBerry UEM Web Services provide a RESTful endpoint structure that is accessed using HTTP. Requests are formatted in JSON and return JSON-formatted responses.

You need the following information to use the BlackBerry UEM REST API:

  1. Your organization’s tenant ID (previously known as SRPID), also referred to as 'tenantGuid' in web service routes.
    • Ask your organization’s UEM administrator for the tenant ID of the UEM domain. The administer would have specified the tenant ID during the UEM installation process.
    • The administrator can also scan the log file for the BlackBerry UEM Core component for the 'tenantID'.
  2. The login information (username and password) for a UEM administrator account.
    • The REST Web Services require the login information for an administrator account to enable remote administration of the UEM domain.
    • The administrator can create a dedicated administrator account for use by the REST Web Services.
  3. If your API client is outside the firewall and it needs to access these APIs, you can connect over BlackBerry’s secure connectivity connection server (BCP).
    • Refer to 'Access On-Premise UEM web service securely' in Examples section in this document.
    • Ask organization’s UEM administrator to enable access to public web services under 'Settings->General->Public web service access' in UEM administration console.
    • Ask organization’s UEM administrator for BlackBerry’s secure connectivity connection server (BCP) host and port.

Resources

Resources represent the high-level entities of the service. They contain the methods and business logic to interact with the service.

Data types

The data types represent the payloads (both request and response) of the resource methods. Note that fields that are not assigned a value are not returned in the response and the client should be programmed to check for null values.

NOTE: The API utilizes custom media types to differentiate requests and responses. See each resource method for the applicable media type to use when requesting/receiving content from the server.

Authentication

The API is secured by both user authentication as well as user authorization. This two-layer security guarantees that only authenticated user have access to the system and that only properly authorized users have access to certain parts of the system.

NOTE: All authenticated REST requests are authenticated using the HTTP Authorization header. If authentication fails a 401 error is returned.

There are two authentication type supported.

Basic Authentication (On premise only)

See the Request Authentication Header example below to learn how to request and utilize the authentication header required to make requests.

OAuth Authentication

See the REST API OAuth Reference for examples and how to configure and deploy OAuth applications.

Errors

Many 400 and 500 level responses from the server will provide the following Error payload to help you better understand the error condition, when possible. In those cases the Content-Type response header will be application/vnd.blackberry.error-v1+json.

Sample error response body:

{
  "id" : "APPLICATION_NOT_FOUND",
  "subStatusCode" : 113,
  "message" : "Application not found."
}
NOTE: Every API may return 403 Forbidden if the authenticated user is not authorized to perform the action.

Sample not authorized response body:

{
  "id" : "NOT_AUTHORIZED",
  "subStatusCode" : 403,
  "message" : "Not authorized to complete the request."
}

Entities

To better provide dynamic functionality to the APIs, a number of components within UEM are exposed via a generic interface. This allows UEM to expose new metadata without changes to the APIs. An example of this is UEM Profiles. BlackBerry is constantly adding new Profile types and expanding existing Profile types. Providing a generic API and metadata allows developers the ability to discover new features and functionality dynamically in their applications.

With this new model comes a new API that will expose these entities in a common and generic way. It can be a bit overwhelming at first to work with metadata and generic APIs, but the benefit far outweighs the initial ramp up time.

Entities APIs

Entity Definitions vs. Entities

When dealing with generic entities it is important to understand the difference between an Entity Definition and an Entity.

Entity Definition An Entity Definition is the description of the Entity. It describes the properties, types, sizes, constraints, UI representations, etc. All Entities have an Entity Definition they are defined from.
Entity An Entity is an instance of an Entity Definition. For example, an Email Profile is defined as an Entity Definition. All instances of the Email Profile are considered Entities.
Understanding entity definitions

It is important to understand an entity's settings and its relationship to other entities. It is recommended to review the entity definition before creating or updating an entity instance. Each setting has a data type that defines the allowable values for the setting. Please see the Entity data types section for a detailed description of all the data types. Note the following:

  • Some settings are included in an entity definition for completeness, but are not intended to be used when creating or updating an entity instance. This includes: date, createdBy, lastModifiedTime, modifiedBy, modifiedBySystem, rank, isDefault, hideAssigningToUser, hideAssigningToGroup, hideAssignment, assignedToUsers, effectiveForUsers, indirectlyAssignedToUsers, assignedToGroups, effectiveUserAssignments, effectiveGroupAssignments, assignedToResourceSets, adminValidationRequired, allGoodPolicySetId.
    • Supported entity definitions

    The following example shows how to return the set of supported entities. This list can change based on the version and updates to UEM, so it is important to call this API on your specific UEM instance to get the most up to date list. We will support all entities that relate to MDM profiles with CRUD operations for profiles and associated entities within those profiles.

    curl -s -k https://server01:18084/SRP00000/api/v1/entityDefs \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.entitydefinitions-v1+json"

    Click here to see an example response to the API call.

    The following table lists the entity definitions that are currently supported. Support for additional entity definitions will be added in future releases.

    Entity Definition ID Description
    com.blackberry.mdm.common.entity.profile.DynamicsSecurityProfile

    This entityDefId corresponds to the BlackBerry Dynamics profile.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
  • Delete an entity instance
  • Get an entity instance template
  • Create an entity instance
  • Update an entity instance
    		•
    com.blackberry.mdm.common.entity.profile.MobileThreatDetection

    This entityDefId corresponds the CylancePROTECT profile.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
  • Get an entity instance template

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Delete an entity instance
  • Create an entity instance
  • Update an entity instance
    		•
    com.blackberry.mdm.common.entity.ApprovedDeveloperCertificate

    This entityDefId corresponds to managing the approved apps list for CylancePROTECT features by specifying developer certificates.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
  • Get an entity instance template

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Delete an entity instance
  • Create an entity instance
  • Update an entity instance, note that only the name and description fields can be updated
    		•
    com.blackberry.mdm.common.entity.ApprovedApplication

    This entityDefId corresponds to managing the approved apps list for CylancePROTECT features by specifying app details.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
  • Get an entity instance template

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Delete an entity instance
  • Create an entity instance
  • Update an entity instance, note that only the description field can be updated
    		•
    com.blackberry.mdm.common.entity.mobilethreatdefence.RestrictedDeveloperCertificate

    This entityDefId corresponds to managing the restricted apps list for CylancePROTECT features by specifying developer certificates.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
  • Get an entity instance template

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Delete an entity instance
  • Create an entity instance
  • Update an entity instance, note that only the name and description fields can be updated
    		•
    com.blackberry.mdm.common.entity.mobilethreatdefence.RestrictedApplication

    This entityDefId corresponds to managing the restricted apps list for CylancePROTECT feature by specifying app details.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
  • Get an entity instance template

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Delete an entity instance
  • Create an entity instance
  • Update an entity instance, note that only the description field can be updated
    		•
    com.blackberry.mdm.common.entity.MtdGeneralSettings

    This entityDefId corresponds to the general settings for certain CylancePROTECT features.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Update an entity instance
    		•
    com.blackberry.mdm.common.entity.MtdSafeBrowsingSettings

    This entityDefId corresponds to the settings for the CylancePROTECT safe browsing feature.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances

    • The following operations are supported only when the licensed CylancePROTECT service is enabled:

  • Update an entity instance
    		•
    com.blackberry.mdm.common.entity.AuthDelegate

    This entityDefId corresponds to the authentication delegates configured in a BlackBerry Dynamics profile.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
    		•
    com.blackberry.mdm.common.entity.Application

    This entityDefId corresponds to applications that are linked from other entities, for example, the MtdSafeBrowsingSettings entity.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
    		•
    com.blackberry.mdm.common.entity.AppStore

    This entityDefId corresponds to an application store that is linked from other entities, for example, the Application entity.

    Supported operations for this entity:

  • Get the entity definition
  • Get the entity instances
    		•
    Get an entity instance template

    To make the process of creating an entity easier, an entity instance template can be downloaded that includes all of the fields with prepopulated default values. Once the template is retrieved, any updates can be applied to the response, and can then be sent back to the create method that is documented below.

    curl -s -k https://server01:18084/SRP00000/api/v1//entities/{entityDefId}/template \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.entityinstance-v1+json"
    Create/update an entity

    To create an instance of an entity definition, you must provide all of the required fields as defined in the entity definition. As per the documentation above, getting an entity instance template and applying updates is the preferred method to create an entity.

    curl -s -k https://server01:18084/SRP00000/api/v1//entities/{entityDefId} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Content-Type: application/vnd.blackberry.entityinstance-v1+json" \
-d '{
     "entityDefId": "com.blackberry.mdm.common.entity.profile.DynamicsSecurityProfile",
     "settings": {
         "allPwdAndroidFingerprintAndroidFingerprintColdStart": true,
         "allPwdFormatMaxRepeatX": 3,
         "allWearableAllowAutoReconnect": true,
         "allPwdBiometricsXTOUCHRequirePasswordNotTouchIDPeriod": 1,
         "allPwdFormatIsAlphaNum": true,
         "allWearableAllow": true,
         "allPwdDisallowNumericSequence": true,
         "allDataLeakagePreventionPreventScreenCapture": true,
         "allDataLeakagePreventionPreventiOSScreenRecordingSharing": true,
         "allAllowedCertsUsePkcs12CertEnabled": true,
         "allPwdExpirationX": 60,
         "allPwdAndroidFingerprint": true,
         "allPwdBiometricsXTOUCHFACEColdStart": false,
         ...
     }
}'

    Examples

    The following examples outline how to execute initial use cases to exercise the API.

    NOTE: All routes include tenantGuid which is the same as the initial SRPID entered when BlackBerry UEM is installed.
    Verify Server is Running

    The following request verifies that the server is up and running. This API is not authenticated.

    curl -s -k https://server01:18084/SRP00000/api/v1/util/ping
    Request Authentication Header

    The following request generates the authentication header used in subsequent requests. This API is not authenticated.

    NOTE: The password in the request must be base64-encoded. 
    curl -s -k https://server01:18084/SRP00000/api/v1/util/authorization \
-H "Content-Type: application/vnd.blackberry.authorizationrequest-v1+json" \
-d '{
  "provider" : "LOCAL",
  "username" : "pmorley",
  "password" : "cGFzc3dvcmQ="
}'
    Set a custom correlation-id

    The following example shows how to set a custom correlation-id in the request header

    curl -s -k https://server01:18084/SRP00000/api/v1/groups \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.groups-v1+json" \
-H "Correlation-Id: customCorrelationId"
    Request a Profile by Name

    The following example shows how to request a specific Profile by name.

    curl -s -k https://server01:18084/SRP00000/api/v1/profiles?query=name=test \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.profiles-v1+json"
    Request all Groups

    The following example shows how to request all the groups

    curl -s -k https://server01:18084/SRP00000/api/v1/groups \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.groups-v1+json"
    Assign a Profile to a Group

    Using the responses from the previous two calls the Profile can be assigned to a specific Group

    curl -s -k https://server01:18084/SRP00000/api/v1/profiles/{profileGuid}/groups \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Content-Type: application/vnd.blackberry.groups-v1+json" \
-d '{
  "groups" : [ {
    "guid" : "{Group GUID to assign from previous call}"
  } ]
}'
    Access On-Premise UEM web service securely

    To access On-Premise web services using BlackBerry Infrastructure proxy, you must provide the extra proxy information in the request

    curl --proxy http://proxyserverhost:proxyserverport \
--proxy-header "Tenant-Id: SRP00000" \
--proxy-header "Origin-Server-Id: bws" \
-s -k https://server01:18084/SRP00000/api/v1/util/ping

    PowerShell

    The following PowerShell examples show how to execute basic use cases and exercise the API.

    PowerShell Examples