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 IDDescriptionSupported operations
    com.blackberry.mdm.common.entity.AllowedDomainRouteThis 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.
  • Get the entity definition
  • com.blackberry.mdm.common.entity.AntivirusVendorThis entityDefId corresponds to antivirus vendors that are linked from other entities, for example, a compliance profile.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.AppRestrictionThis entityDefId corresponds to a restricted Application that are linked from other entities, for example, a compliance profile.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.AppServerThis 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.
  • Get the entity definition
  • com.blackberry.mdm.common.entity.AppServerRouteThis 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.
  • Get the entity definition
  • com.blackberry.mdm.common.entity.AppStoreThis entityDefId corresponds to an application store that is linked from other entities, for example, the AppRestriction entity.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.ApplicationThis entityDefId corresponds to applications that are linked from other entities, for example, the MtdSafeBrowsingSettings entity.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.ApprovedApplicationThis entityDefId corresponds to managing the approved apps list for BlackBerry Protect features by specifying app details. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.ApprovedDeveloperCertificateThis entityDefId corresponds to managing the approved apps list for BlackBerry Protect features by specifying developer certificates. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.AuthDelegateThis entityDefId corresponds to the authentication delegates configured in a BlackBerry Dynamics profile.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.ClusterThis entityDefId corresponds to BlackBerry Proxy clusters.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.DefaultDomainRouteThis 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.
  • Get the entity definition
  • com.blackberry.mdm.common.entity.DeviceHardwareBrandThis 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
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.DeviceHardwareModelThis 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
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.DeviceHardwareVendorThis 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
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.DeviceOsVersionThis entityDefId corresponds to device OS versions that are linked from other entities, for example, a compliance profile.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.DynamicsLibraryThis entityDefId corresponds to the BlackBerry Dynamics library versions that are linked from other entities, for example, a compliance profile.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.EmailTemplateThis entityDefId corresponds to the email templates that are linked from other entities, for example, a compliance profile.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.IPAddressRangeRouteThis 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.
  • Get the entity definition
  • com.blackberry.mdm.common.entity.MtdGeneralSettingsThis entityDefId corresponds to the general settings for certain BlackBerry Protect features. There is only one instance and the External Tenant Id is used as the entityInstanceId. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • com.blackberry.mdm.common.entity.MtdSafeBrowsingSettingsThis entityDefId corresponds to the settings for certain BlackBerry Protect safe browsing features. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.ServerRouteThis 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.
  • Get the entity definition
  • com.blackberry.mdm.common.entity.mobilethreatdefence.RestrictedApplicationThis entityDefId corresponds to managing the restricted apps list for BlackBerry Protected feature by specifying app details. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.mobilethreatdefence.RestrictedDeveloperCertificateThis entityDefId corresponds to managing the restricted apps list for BlackBerry Protect features by specifying developer certificates. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.ActivationPolicyThis entityDefId corresponds to the Activation profile.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.ComplianceProfileThis entityDefId corresponds to the compliance profile.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.DynamicsConnectivityProfileThis entityDefId corresponds to the BlackBerry Dynamics connectivity profile.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.DynamicsSecurityOverrideProfileThis entityDefId corresponds to the BlackBerry Dynamics override profile.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.DynamicsSecurityProfileThis entityDefId corresponds to the BlackBerry Dynamics profile.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.MobileThreatDetectionThis entityDefId corresponds to the BlackBerry Protect profile. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Delete an entity instance
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • Get an entity instance template
  • com.blackberry.mdm.common.entity.profile.OrganizationalNoticeProfileThis entityDefId corresponds to the Organization notices configured in General settings.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.settings.AndroidHardwareKeyAttestationSettingsThis entityDefId corresponds to the Android hardware attestation settings for BlackBerry Protect. There is only one instance and the External Tenant Id is used as the entityInstanceId. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • com.blackberry.mdm.common.entity.settings.AppleDeviceCheckAttestationSettingsThis entityDefId corresponds to the iOS App Integrity settings for BlackBerry Protect. There is only one instance and the External Tenant Id is used as the entityInstanceId. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • com.blackberry.mdm.common.entity.settings.AttestableApplicationThis entityDefId corresponds to the applications available for attestation, which can be configured in the SafetyNet attetation settings and iOS app integrity check settings entities.
  • Get the entity definition
  • Get the entity instances
  • com.blackberry.mdm.common.entity.settings.DeviceCheckAttestationKeyThis entityDefId corresponds to the iOS App Integrity device check key. This entity is supported only when the licensed BlackBerry Protect service is enabled.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • Create an entity instance
  • com.blackberry.mdm.common.entity.settings.KnoxAttestationSettingsThis entityDefId corresponds to the Samsung Knox Workspace attestation settings. There is only one instance and the External Tenant Id is used as the entityInstanceId.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • com.blackberry.mdm.common.entity.settings.SafetyNetAttestationSettingsThis entityDefId corresponds to the Android SafetyNet attestation settings. There is only one instance and the External Tenant Id is used as the entityInstanceId.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • com.blackberry.mdm.common.entity.settings.WindowsAttestationSettingsThis entityDefId corresponds to the Windows 10 attestation settings. There is only one instance and the External Tenant Id is used as the entityInstanceId.
  • Get the entity definition
  • Get the entity instances
  • Update an entity instance
  • com.blackberry.platform.common.api.entity.TenantSettingsThis entityDefId corresponds to general representation of Tenant settings. This entity is abstract and allows only enumerate to return all sub-settings.
  • 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,
             ...
         }
    }'
    
    Enclosed entities

    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
                    }
                }
            ]
        }
    }'
    
    Allowed or restricted device models in the compliance profile

    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.

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

    Certificate management

    This section describes the principles and functionality of certificate management in BlackBerry UEM.

    NOTE: As of API version 12.13.0, certificate management is limited to certificates that belong to SCEP profiles, User credential profiles and User certificates. The API is designed at a level of abstraction so that the number of supported certificate types can be extended in the future without changing the API contract.

    Logical data types and resources:

    Certificate

    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.

    Certificate Bundle

    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.

    Embedded Certificate

    Represents the relationship between a particular Certificate and other resources: User, Profile, Certificate, Certificate Bundle, User Devices, and BlackBerry Dynamics Applications.

    Certificate Enrollment

    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.


    Examples of certificate management operations:

    Request Embedded Certificates for a User

    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"
    
    Request Certificate Enrollments for an Embedded Certificate and User

    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"
    
    Downloading public key Certificate

    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
    
    NOTE: There are some cases where the X.509 public key certificate is not available for download. See Getting the available operations for a Certificate for details.
    Getting the available operations for a Certificate

    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:

    • GET: indicates that the X.509 public key certificate can be downloaded
    • DELETE: indicates that the certificate can be deleted
    • PATCH: indicates that the certificate can be renewed

    Deleting a Certificate
    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}"
    
    Renewing a Certificate
    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}"
    
    Certificate Bundle operations

    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:

    • DELETE: indicates that the bundle can be deleted
    • PATCH: indicates that the bundle can be renewed

    Deleting a Certificate Bundle

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

    Renewing a Certificate Bundle

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

    Uploading certificates

    User-related certificate functionality can be divided into two main categories:

    • PKI-driven certificate enrollment (SCEP profile, User credential profile with a PKI connector)
    • Manually uploaded certificates (User certificate, User credential profile with a manually uploaded certificate)
    For PKI-driven profiles, the certificate is issued automatically by the PKI infrastructure while enrolling the profile to a device or application. For manually uploaded certificates, the PKCS#12 certificate container file should be uploaded to UEM as a separate operation. UEM supports two types of manually uploaded certificates:
    • User credential profile with a manually uploaded certificate.

      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.

    • User certificate.

      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.

    Uploading certificate for a User credential profile with manual connector type for the non-BlackBerry Dynamics platform.

    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:

    • A certificate metadata JSON object that holds a Base64-encoded PKCS#12 password, Content-Type: application/vnd.blackberry.deviceusercertificatemetadata-v1+json
    • A binary PKCS#12 certificate container body, Content-Type: application/pkcs12
    Given the pkcs12_file.p12 file and the password, the following command provides an example of uploading a certificate for a user credentials profile that is assigned to a user:

    (                                                                                             \
    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 user certificate for a User for non-BlackBerry Dynamics platform
    NOTE: This option is provided only for compatibility with related User certificate functionality in UEM management console. It is a best practice to use the User Credential Profile with manually uploaded certificate instead.

    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:

    • The certificate is uploaded under User instead of under User Profile Assignment.
    • The POST method is used instead of PUT because each new request adds a new user certificate and does not affect pre-existing uploaded certificates.

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

    Replacing a user certificate uploaded for non-BlackBerry Dynamics platform

    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.

    Uploading a BlackBerry Dynamics user certificate for a user

    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"'
    
    Replacing a BlackBerry Dynamics user certificate

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

    Samples

    PowerShell

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

    PowerShell Examples

    OAuth

    The following PowerShell, Java, and Postman examples show how to exercise API using OAuth.

    OAuth Examples