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:
Resources represent the high-level entities of the service. They contain the methods and business logic to interact with the service.
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.
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.
There are two authentication type supported.
See the Request Authentication Header example below to learn how to request and utilize the authentication header required to make requests.
See the REST API OAuth Reference for examples and how to configure and deploy OAuth applications.
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."
}
Sample not authorized response body:
{
"id" : "NOT_AUTHORIZED",
"subStatusCode" : 403,
"message" : "Not authorized to complete the request."
}
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.
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. |
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:
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 | Supported operations |
|---|---|---|
| com.blackberry.mdm.common.entity.AllowedDomainRoute | This entityDefId corresponds to the allowed domain routes that are linked from BlackBerry Connectivity profiles. As an enclosed entity, they cannot be operated on by themselves and are only present within BlackBerry Connectivity profile instances. | |
| com.blackberry.mdm.common.entity.AntivirusVendor | This entityDefId corresponds to antivirus vendors that are linked from other entities, for example, a compliance profile. | |
| com.blackberry.mdm.common.entity.AppRestriction | This entityDefId corresponds to a restricted Application that are linked from other entities, for example, a compliance profile. | |
| com.blackberry.mdm.common.entity.AppServer | This entityDefId corresponds to the app servers that are linked from BlackBerry Connectivity profiles. As an enclosed entity, they cannot be operated on by themselves and are only present within BlackBerry Connectivity profile instances. | |
| com.blackberry.mdm.common.entity.AppServerRoute | This entityDefId corresponds to the app server routes that are linked from BlackBerry Connectivity profiles. As an enclosed entity, they cannot be operated on by themselves and are only present within BlackBerry Connectivity profile 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. | |
| com.blackberry.mdm.common.entity.Application | This entityDefId corresponds to applications that are linked from other entities, for example, the MtdSafeBrowsingSettings entity. | |
| com.blackberry.mdm.common.entity.ApprovedApplication | This entityDefId corresponds to managing the approved apps list for CylancePROTECT features by specifying app details. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.ApprovedDeveloperCertificate | This entityDefId corresponds to managing the approved apps list for CylancePROTECT features by specifying developer certificates. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.AuthDelegate | This entityDefId corresponds to the authentication delegates configured in a BlackBerry Dynamics profile. | |
| com.blackberry.mdm.common.entity.Cluster | This entityDefId corresponds to BlackBerry Proxy clusters. | |
| com.blackberry.mdm.common.entity.DefaultDomainRoute | This entityDefId corresponds to the default domain routes that are linked from BlackBerry Connectivity profiles. As an enclosed entity, they cannot be operated on by themselves and are only present within BlackBerry Connectivity profile 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 and 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 | |
| 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 and SM-G973N are specific Galaxy S10 models. Click here for additional information on device hardware | |
| 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 or 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 | |
| com.blackberry.mdm.common.entity.DeviceOsVersion | This entityDefId corresponds to device OS versions that are linked from other entities, for example, a compliance profile. | |
| 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. | |
| com.blackberry.mdm.common.entity.EmailTemplate | This entityDefId corresponds to the email templates that are linked from other entities, for example, a compliance profile. | |
| com.blackberry.mdm.common.entity.IPAddressRangeRoute | This entityDefId corresponds to the IP address ranges that are linked from BlackBerry Connectivity profiles. As an enclosed entity, they cannot be operated on by themselves and are only present within BlackBerry Connectivity profile instances. | |
| com.blackberry.mdm.common.entity.MtdGeneralSettings | This entityDefId corresponds to the general settings for certain CylancePROTECT features. There is only one instance and the External Tenant Id is used as the entityInstanceId. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.MtdSafeBrowsingSettings | This entityDefId corresponds to the settings for certain CylancePROTECT safe browsing features. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.ServerRoute | This entityDefId corresponds to the additional server routes that are linked from BlackBerry Connectivity profiles. As an enclosed entity, they cannot be operated on by themselves and are only present within BlackBerry Connectivity profile instances. | |
| com.blackberry.mdm.common.entity.mobilethreatdefence.RestrictedApplication | This entityDefId corresponds to managing the restricted apps list for the CylancePROTECT feature by specifying app details. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.mobilethreatdefence.RestrictedDeveloperCertificate | This entityDefId corresponds to managing the restricted apps list for CylancePROTECT features by specifying developer certificates. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.profile.ActivationPolicy | This entityDefId corresponds to the Activation profile. | |
| com.blackberry.mdm.common.entity.profile.ComplianceProfile | This entityDefId corresponds to the compliance profile. | |
| com.blackberry.mdm.common.entity.profile.DynamicsConnectivityProfile | This entityDefId corresponds to the BlackBerry Dynamics connectivity profile. | |
| com.blackberry.mdm.common.entity.profile.DynamicsSecurityOverrideProfile | This entityDefId corresponds to the BlackBerry Dynamics override profile. | |
| com.blackberry.mdm.common.entity.profile.DynamicsSecurityProfile | This entityDefId corresponds to the BlackBerry Dynamics profile. | |
| com.blackberry.mdm.common.entity.profile.MobileThreatDetection | This entityDefId corresponds to the CylancePROTECT profile. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.profile.OrganizationalNoticeProfile | This entityDefId corresponds to the Organization notices configured in General settings. | |
| com.blackberry.mdm.common.entity.settings.AndroidHardwareKeyAttestationSettings | This entityDefId corresponds to the Android hardware attestation settings for CylancePROTECT. There is only one instance and the External Tenant Id is used as the entityInstanceId. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.settings.AppleDeviceCheckAttestationSettings | This entityDefId corresponds to the iOS App Integrity settings for CylancePROTECT. There is only one instance and the External Tenant Id is used as the entityInstanceId. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.settings.AttestableApplication | This entityDefId corresponds to the applications available for attestation, which can be configured in the SafetyNet attetation settings and iOS app integrity check settings entities. | |
| com.blackberry.mdm.common.entity.settings.DeviceCheckAttestationKey | This entityDefId corresponds to the iOS App Integrity device check key. This entity is supported only when the licensed CylancePROTECT service is enabled. | |
| com.blackberry.mdm.common.entity.settings.KnoxAttestationSettings | This entityDefId corresponds to the Samsung Knox Workspace attestation settings. There is only one instance and the External Tenant Id is used as the entityInstanceId. | |
| com.blackberry.mdm.common.entity.settings.SafetyNetAttestationSettings | This entityDefId corresponds to the Android SafetyNet attestation settings. There is only one instance and the External Tenant Id is used as the entityInstanceId. | |
| com.blackberry.mdm.common.entity.settings.WindowsAttestationSettings | This entityDefId corresponds to the Windows 10 attestation settings. There is only one instance and the External Tenant Id is used as the entityInstanceId. | |
| com.blackberry.platform.common.api.entity.TenantSettings | This entityDefId corresponds to general representation of Tenant settings. This entity is abstract and allows only enumerate to return all sub-settings. |
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"
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,
...
}
}'
An enclosed entity is an entity whose instance only exists as part of the parent entity that it is linked from. An enclosed entity instance cannot be created, updated, deleted, or fetched on its own, only from its parent entity. For example, com.blackberry.mdm.common.entity.AllowedDomainRoute is an enclosed entity in the com.blackberry.mdm.common.entity.profile.DynamicsConnectivityProfile entity. To create or update an allowed domain route, the settings for the new allowed domain route are specified in the request to create or update a BlackBerry Dynamics connectivity profile.
curl -s -k https://server01:18084/SRP00000/api/v1//entities/com.blackberry.mdm.common.entity.profile.DynamicsConnectivityProfile \
-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.DynamicsConnectivityProfile",
"settings": {
"name": "Sample Dynamics Connectivity profile",
"description": "This is just a sample Dynamics connectivity profile",
"routeAllTraffic": false,
"defaultDomains": [
{
"entityDefId": "com.blackberry.mdm.common.entity.DefaultDomainRoute",
"settings": {
"primaryCluster": {
"entityDefId": "com.blackberry.mdm.common.entity.Cluster",
"entityInstanceId": "e1433bc5-5523-4cd7-9c7b-96ee2b95b06f",
"settings": {
"name": "First"
}
},
"domainName": "defaultdomain.sample.blackberry.net",
"routeType": "BLACKBERRY_PROXY_CLUSTER",
"nameEditable": true,
"portEditable": true,
"routeTypeEditable": true,
"reservedRemovable": true
}
}
],
"defaultAllowedDomainRouteType": "DIRECT",
"allowedDomains": [
{
"entityDefId": "com.blackberry.mdm.common.entity.AllowedDomainRoute",
"settings": {
"domainName": "alloweddomain.sample.blackberry.net",
"routeType": "DIRECT",
"nameEditable": true,
"portEditable": true,
"routeTypeEditable": true,
"reservedRemovable": true
}
}
],
"additionalServers": [
{
"entityDefId": "com.blackberry.mdm.common.entity.ServerRoute",
"settings": {
"primaryCluster": {
"entityDefId": "com.blackberry.mdm.common.entity.Cluster",
"entityInstanceId": "e1433bc5-5523-4cd7-9c7b-96ee2b95b06f",
"settings": {
"name": "First"
}
},
"serverName": "additionserver.sample.blackberry.com",
"port": 8005,
"routeType": "BLACKBERRY_PROXY_CLUSTER",
"nameEditable": true,
"portEditable": true,
"routeTypeEditable": true,
"reservedRemovable": true
}
}
]
}
}'
The allowed or restricted device models in a compliance profile are controlled by three separate but 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. 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 given the highest priority, then brands, and then models. For example, if only the Galaxy S10 is set in the device hardware brands allowed or restricted list, and Samsung is also set in the vendors allowed or restricted list, the Galaxy S9 and all of 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 has higher priority. Similarly, if only SM-G973F and SM-G973N are set in the device hardware models allowed or restricted list, and Galaxy S10 is set in the brands allowed or restricted list, model SM-G973FD and all other models are still allowed or restricted even though they are not explicitly in the models list, because it is a Galaxy S10 device and the brand list has 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 management console will show all device hardware models as selected because it displays all of 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 or restricted list, it is also recommended to set all models for that brand in the device hardware model allowed or restricted list. This maintains the compliance state of all current devices if the name of a hardware brand changes.
The following examples outline how to execute initial use cases to exercise the API.
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
The following request generates the authentication header used in subsequent requests. This API is not authenticated.
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="
}'
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"
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"
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"
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}"
} ]
}'
To access On-Premise web services using BlackBerry Infrastructure proxy, you must provide the extra proxy information in the request. The Origin-Server-Id is always "bws". Ask organization’s UEM administrator for BlackBerry’s secure connectivity connection server (BCP) host and port. Administrator can find the information in Admin console at Settings->General Settings->BlackBerry Web Services access
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
This section describes the principles and functionality of certificate management in BlackBerry UEM.
The certificate resource represents the certificate body managed by UEM. The certificate may have a private key; however, the API provides access only to a public key certificate of that private key. Private key data is not exposed in the API due to security considerations. The public key certificate is returned in a DER-encoded X.509 format. Depending on the nature of the certificate, it can be deleted or renewed.
Profiles of external PKI (for example OpenTrust or Entrust) can be configured to return multiple key pairs per enrollment. Such enrollments will simultaneously install multiple certificates on the device or application. Similar multi-key enrollment can be archived with a manual uploading PKCS#12 file that contains multiple keys. All related keys are managed in the API as individual certificates; however, deleting or renewing individual certificates has no purpose without other certificates of the same multi-key enrollment. To provide consistent deletion and renewal for multiple key pairs certificate enrollments, the API introduces the concept of a Certificate Bundle. A Certificate Bundle entity is a group of Certificates that can only be deleted or renewed as a group. If a certificate belongs to a bundle, then renew and delete operations are available only for a Certificate Bundle entity. The API does not permit combining individual certificates into a bundle or extracting certificates from a bundle.
Represents the relationship between a particular Certificate and other resources: User, Profile, Certificate, Certificate Bundle, User Devices, and BlackBerry Dynamics Applications.
A list of Certificate Enrollments provides information about certificate usage. Certificate Enrollment links Embedded Certificate to a particular endpoint (User Device or BlackBerry Dynamics Application) where a related certificate is installed.
This operation is an entry point for retrieving user-related certificate data.
curl -s -k https://server01:18084/SRP00000/api/v1/users/{userGUID}/embeddedCertificates \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.embeddedcertificates-v1+json"
Each of the returned Embedded Certificates provides the following information:
Embedded Certificate can be requested individually by it's GUID for a User:
curl -s -k https://server01:18084/SRP00000/api/v1/users/{userGUID}/embeddedCertificates/{embeddedCertificateGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.embeddedcertificate-v1+json"
or as a root resource:
curl -s -k https://server01:18084/SRP00000/api/v1//embeddedCertificates/{embeddedCertificateGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.embeddedcertificate-v1+json"
The following request provides information about User Devices and BlackBerry Dynamics Applications that have installed the related Certificate. Certificate Enrollments for BlackBerry Dynamics applications contain a status that gives information about the stage of the certificate lifecycle on the device.
curl -s -k https://server01:18084/SRP00000/api/v1/users/{userGUID}/embeddedCertificates/{embeddedCertificateGUID}/certificateEnrollments \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.certificateenrollments-v1+json"
Using the reference provided in the related Embedded Certificate, the client may download the X.509 public key certificate of the managed certificate. The API client may use the X.509 certificate to check the validity or to extract certificate details such as the Issuer, Subject, Serial number, validity period and so on. The HTTP response also provides a certificate filename in the Content-Disposition HTTP header. The default (and currently, the only supported) response Content-Type is the application/pkix-cert that corresponds to the DER-encoded X.509 certificate.
curl -s -k https://server01:18084/SRP00000/api/v1/pki/certificates/{certificateGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/pkix-cert" \
> downloaded_certificate_file.cer
Depending on the nature of the certificate, it may have the ability to be deleted or renewed. These operations can be asynchronous because they may involve communication with an external PKI, enrolled devices, or BlackBerry Dynamics applications. There may be some cases where the X.509 public key certificate is not available for download. To get information about the possibility of downloading, deleting, or renewing a certificate, the API client should use the OPTIONS method for the resource:
curl -s -k -i -X OPTIONS https://server01:18084/SRP00000/api/v1/pki/certificates/{certificateGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}"
The client should then analyze the returned Allow HTTP header for the presence of HTTP methods:
curl -s -k -i -X DELETE https://server01:18084/SRP00000/api/v1/pki/certificates/{certificateGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}"
curl -s -k -i -X PATCH https://server01:18084/SRP00000/api/v1/pki/certificates/{certificateGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}"
The presence of a reference to a Certificate Bundle in an Embedded Certificate indicates that the related certificate belongs to a bundle. The following request retrieves a Certificate Bundle that consists of a list of references to Certificates that belong to the bundle.
curl -s -k https://server01:18084/SRP00000/api/v1/pki/bundles/{certificateBundleGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.certificatebundle-v1+json"
Depending on the nature of the certificate bundle, it may have the ability to be deleted or renewed. Deleting or renewing a bundle applies to all of the certificates that it contains. These operations can be asynchronous because they may include communication with an external PKI, enrolled devices, or BlackBerry Dynamics applications. To get information about the possibility of these operations, the API client should use the OPTIONS method for the resource:
curl -s -k -i -X OPTIONS https://server01:18084/SRP00000/api/v1/pki/bundles/{certificateBundleGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}"
Then the client should analyze the returned Allow HTTP header for the presence of HTTP methods:
curl -s -k -i -X DELETE https://server01:18084/SRP00000/api/v1/pki/bundles/{certificateBundleGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}"
curl -s -k -i -X PATCH https://server01:18084/SRP00000/api/v1/pki/bundles/{certificateBundleGUID} \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}"
User-related certificate functionality can be divided into two main categories:
The administrator creates the profile and assigns it to a group or user directly. PKCS#12 certificate container file to be uploaded for resulting user profile assignment by administrator or device user (pending Manage user certificates self-service permission). This option is the preferred way of managing manually uploaded certificates as it offers the administrator more control. As of UEM version 12.13.0, User credential profiles with manually uploaded certificates do not support BlackBerry Dynamics applications.
The administrator or device user (pending Manage user certificates self-service permission) uploads the PKCS#12 certificate file directly to a User. This option is not recommended for MDM, but is the only supported method for BlackBerry Dynamics applications.
The related User credential profile should already be created and assigned to a user or group so that the user already has the related user profile assignment with the USER_CREDENTIAL profile category. The following operation returns user profile assignments:
curl -s -k https://server01:18084/SRP00000/api/v1/users/{userGUID}/profiles \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Accept: application/vnd.blackberry.profileassignments-v1+json"
From the API perspective, uploading certificate for a User credential profile with manual connector type for the non-BlackBerry Dynamics platform involves uploading the PKCS#12 certificate container with its password to a user profile assignment via a PUT request to a user profile assignment resource where the request body has a multipart/related Content-Type that consists of two boundary parts:
( \
printf -- '--certPartsBoundary\n' ;\
printf -- 'Content-Type: application/vnd.blackberry.deviceusercertificatemetadata-v1+json\n' ;\
printf -- '\n' ;\
printf -- '{ "password":"cGFzc3dvcmQ=" }\n' ;\
printf -- '--certPartsBoundary\n' ;\
printf -- 'Content-Type: application/pkcs12\n' ;\
printf -- 'Content-Disposition: attachment; filename="pkcs12_file.p12"\n' ;\
printf -- 'Content-Id: rootIdentifier\n' ;\
printf -- '\n' ;\
cat pkcs12_file.p12 ;\
printf -- '\n' ;\
printf -- '\n' ;\
printf -- '--certPartsBoundary--' \
) | curl -s -k -X PUT --data-binary @- https://server01:18084/SRP00000/api/v1/users/{userGUID}/profiles/{profileGUID}/embeddedCertificates \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H 'Content-Type: multipart/related; boundary="certPartsBoundary"; start="rootIdentifier"'
The response provides a list of Embedded Certificates for each of the private keys uploaded within the PKCS#12 container. If the profile already has uploaded certificates, the certificates are replaced with the new uploaded ones.
Uploading a non-BlackBerry Dynamics user certificate for a User is similar to uploading certificate for a User Credential profile described above with the following differences:
( \
printf -- '--certPartsBoundary\n' ;\
printf -- 'Content-Type: application/vnd.blackberry.deviceusercertificatemetadata-v1+json\n' ;\
printf -- '\n' ;\
printf -- '{ "password":"cGFzc3dvcmQ=" }\n' ;\
printf -- '--certPartsBoundary\n' ;\
printf -- 'Content-Type: application/pkcs12\n' ;\
printf -- 'Content-Disposition: attachment; filename="pkcs12_file.p12"\n' ;\
printf -- 'Content-Id: rootIdentifier\n' ;\
printf -- '\n' ;\
cat pkcs12_file.p12 ;\
printf -- '\n' ;\
printf -- '\n' ;\
printf -- '--certPartsBoundary--' \
) | curl -s -k -X POST --data-binary @- https://server01:18084/SRP00000/api/v1/users/{userGUID}/embeddedCertificates \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H 'Content-Type: multipart/related; boundary="certPartsBoundary"; start="rootIdentifier"'
The response provides a list of Embedded Certificates for each of the private keys uploaded with the PKCS#12 container. This operation implicitly creates a new user profile assignment with a USER_CERTIFICATE profile category. The resulting structure of resources becomes similar to other types of certificates. The profile assignment can be queried like any other profile assignment. Using the Profile GUID provided in a profile assignment, client may delete a profile, and this operation will also delete the profile assignment and the related user certificate as well. The profile can't be queried as a profile and can't be unassigned from a user or assigned to another user or group because it is strictly bound to the original user.
An existing uploaded non-BlackBerry Dynamics user certificate is treated as a user profile assignment similar to a certificate uploaded for a User credential profile. Replacing the certificate is the same as uploading or replacing the certificate for a User credential profile.
UEM does not manage passwords for BlackBerry Dynamics certificates, so the upload process is implemented as a pure PKCS#12 data upload with an application/pkcs12 Content-Type. All other details are identical to uploading a non-BlackBerry Dynamics user certificate for a User described above.
curl -s -k -X POST --data-binary @pkcs12_file.pfx https://server01:18084/SRP00000/api/v1/users/{userGUID}/embeddedCertificates \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Content-Type: application/pkcs12" \
-H 'Content-Disposition: attachment; filename="pkcs12_file.pfx"'
An existing uploaded BlackBerry Dynamics user certificate is treated as a user profile assignment similar to a certificate uploaded for a User credential profile. Replacing the certificate is identical to uploading or replacing the certificate for a User credential profile. The only difference is that BlackBerry Dynamics certificates are uploaded without a password as pure PKCS#12 data using the application/pkcs12 Content-Type.
curl -s -k -X PUT --data-binary @pkcs12_file.pfx https://server01:18084/SRP00000/api/v1/users/{userGUID}/profiles/{profileGUID}/embeddedCertificates \
-H "Authorization: {insert value from /SRP00000/api/v1/util/authorization call}" \
-H "Content-Type: application/pkcs12" \
-H 'Content-Disposition: attachment; filename="pkcs12_file.pfx"'
The following PowerShell examples show how to execute basic use cases and exercise the API.
PowerShell ExamplesThe following PowerShell, Java, and Postman examples show how to exercise API using OAuth.
OAuth Examples