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:

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

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

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

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."
}

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