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 API changes. 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. Therefore it is recommended to review the entity definition before creating or updatind an entity instance. Each setting has a data type which 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 to get the most up to date list. We will primarily 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.ComplianceProfile

    This entityDefId corresponds to the compliance 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.DynamicsLibrary

    This entityDefId corresponds to the BlackBerry Dynamics library versions that are linked from other entities, for example, a compliance profile.

    Supported operations for this entity:

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

    This entityDefId corresponds to the email templates that are linked from other entities, for example, a compliance profile.

    Supported operations for this entity:

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

    This entityDefId corresponds to the device hardware vendors that are linked from other entities, for example, a compliance profile that specifies allowed/or restricted device models. The device hardware vendor entity reprepresents a specific vendor that makes device hardware. For example, Samsung, Motorola. The device hardware vendor entity is related to com.blackberry.mdm.common.entity.DeviceHardwareBrand as each vendor could make one or more device hardware brands.

    Click here for additional information on device hardware.

    Supported operations for this entity:

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

    This entityDefId corresponds to the device hardware brands that are linked from other entities, for example, a compliance profile that specifies allowed/or restricted device models. The device hardware brand entity reprepresents a specific type of device hardware. For example, Galaxy S9, Galaxy S10 are specific Samsung device brands. The device hardware brand entity is related to com.blackberry.mdm.common.entity.DeviceHardwareModel as each branch could have one or more device hardware models.

    Click here for additional information on device hardware.

    Supported operations for this entity:

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

    This entityDefId corresponds to the device hardware models that are linked from other entities, for example, a compliance profile that specifies allowed/or restricted device models. The device hardware model entity reprepresents a specific device model within a brand. For example, SM-G973F, SM-G973N are specific Galaxy S10 models.

    Click here for additional information on device hardware.

    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.AppRestriction

    This entityDefId corresponds to a restricted Application that are linked from other entities, for example, a compliance profile.

    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 AppRestriction entity.

    Supported operations for this entity:

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

    This entityDefId corresponds to antivirus vendors that are linked from other entities, for example, a compliance profile.

    Supported operations for this entity:

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

    This entityDefId corresponds to device OS versions that are linked from other entities, for example, a compliance profile.

    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,
             ...
         }
    }'
    
    Allowed/restricted device models in the compliance profile

    The allowed/restricted device models in a compliance profile are controlled by three separate yet related entities: com.blackberry.mdm.common.entity.DeviceHardwareVendor, com.blackberry.mdm.common.entity.DeviceHardwareBrand and com.blackberry.mdm.common.entity.DeviceHardwareModel. If a list of allowed/or restricted device hardware vendors are set in the compliance profile, then all device models made by the specified vendors will either be allowed/or restricted. Similarly, if a list of allowed/or restricted device hardware brands are set then all device models for the specified brands will be allowed/or restricted. By setting only the list of allowed/or restricted device hardware models indicates that only those specific models will be allowed or restricted.

    When more than one of device hardware vendors, brands or models are specified, vendors is the highest priority, then brands and then models is the lowest priority. For example, if only the Galaxy S10 is set in device hardware brands allowed/restricted list, and Samsung is also set in the vendors allowed/restricted list, the Galaxy S9 and all its models would be allowed/or restricted because even though its not in the brands list it is made by Samsung and the vendors list is higher priority. Similarly, if only SM-G973F and SM-G973N were set in the device hardware models allowed/restricted list, and Galaxy S10 was set in the brands allowed/restricted list, model SM-G973FD and all other models would still be allowed/or restricted even though they are not explicitly in the models list because it is a Galaxy S10 device and the brand list is higher priority. Note, in these examples when a subset of brands or models are specified, but the parent brand or vendor is also specified the admin console will show all children device hardware models selected as it displays all the device models that are allowed/or restricted. However, getting the compliance profile from the entities API will return only the values explicitly set in the API.

    Warning: when setting a brand in the device hardware brand allowed/restricted list it is also recommended to set all models for that brand in the device hardware model allowed/restricted list. The name of a device hardware brand may change, and though infrequent, in this event this would maintain the compliance of state of all current devices.

    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