Back to top
Home / Knox E-FOTA / Get started / Knox E-FOTA best practices /

Licenses and devices

Last updated September 12th, 2024

License registration

The Knox E-FOTA API provides license management endpoints. You can use these operations to allow your customer to register and delete their Knox licenses through your platform, and you can also show your customer a list of their existing Knox licenses along with relevant license information on your platform. For more information, see the Knox E-FOTA API reference.

After your customer registers their license to Knox E-FOTA, the license seats are automatically consumed once devices are enrolled.

Your customer can also delete a license if they no longer want to use it. Licenses can only be deleted if no devices are active on the license.

License UX recommendations

We recommend that you let your customer view and filter their Knox licenses on your UEM portal with the list of licenses returned from GET /licenses.

License list recommendation

For optimum user experience for your customers, we recommend that your UEM portal highlight licenses that are close to expiration.

Highlight licenses near expiry

Upload devices

Your customer has to upload their devices to Knox E-FOTA to use it to manage firmware on their devices. Use the POST /devices/bulkUpload operation to allow your customers to upload devices to Knox E-FOTA through your UEM portal. This is an asynchronous operation call, and your platform can receive the upload result through webhook notifications.

  • Each request allows up to 10,000 device uploads.
  • deviceId can be IMEI or serial number.
  • Devices uploaded through Knox E-FOTA API are automatically approved when the upload is successful, and are ready to be used by Knox E-FOTA.

Devices should not be uploaded one by one, because this is a very inefficient and time-consuming process. It is much faster and easier to upload all devices in bulk with a single request to POST /devices/bulkUpload. This way, you can save time and resources, and your customers can start managing their devices with Knox E-FOTA as soon as possible.

The device information available to Knox E-FOTA depends on whether the device is enrolled. For more information about enrollment, see Device enrollment.

Device Information Available Unenrolled Devices Enrolled Devices
Device ID ✓ ✓
Model Name ✓ ✓
Sales Code ✓
CSC ✓
OS Version ✓
Firmware Name ✓
Security Patch ✓

Here is a code sample that uploads devices with the Knox E-FOTA API:

private HttpResponse<String> bulkUpload(String accessToken) throws URISyntaxException, IOException, InterruptedException {
    String bulkUploadUrl = API_URI + "devices/bulkUpload";
    String body = "{\n" +
            "\"deviceIds\": [\"imei\",\"sn\"]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(bulkUploadUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "transactionId": "T882582188b10", "code": "00000", "message": "SUCCESS", "data": { "operationId": "64ff499184509e67e8ac736b", "devicesToProcessCount": 2 } }

Subscribe to the KE_DEVICE_BULK_CREATE event on Knox Webhook Notification to receive webhook notifications when devices are uploaded to Knox E-FOTA.

For more information, see the Knox Webhook Notification API reference.

Here is a Java code sample that subscribes to this event on Knox Webhook Notification:

private HttpResponse<String> createBulkUploadSubscription(String callbackUrl) throws URISyntaxException, IOException, InterruptedException {
    String subscriptionUrl = WEBHOOK_URI + "subscriptions";
    String body = "{\n" +
            "\"url\": " + callbackUrl + ",\n" +
            "\"events\": [\n" +
            "\"KE_DEVICE_BULK_CREATE\"\n" +
            "]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(subscriptionUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "payload": { "id": "636c1a692d0f427ee1f07470", "url": "https://some.domain/kwn-results", "events": ["KE_DEVICE_BULK_CREATE"] }}

Device enrollment to Knox E-FOTA

Your customers must enroll their devices for them to be managed by Knox E-FOTA. A device is enrolled when the following conditions are met:

  • The device is uploaded to Knox E-FOTA
  • There is a valid license for the device
  • The Knox E-FOTA client is installed and launched

If a campaign is already assigned to a device when it is enrolled, Knox E-FOTA enforces those campaign settings and firmware policies on that device. If a device is enrolled but not assigned to a campaign, the “Lock current firmware” policy is applied to the device.

Enrollment process through your UEM

This workflow outlines the enrollment process for your customer’s devices.

  1. Your customer registers their license to Knox E-FOTA.
  2. Your customer uploads devices to Knox E-FOTA. Optionally, they can also assign their devices to a campaign.
  3. Your customer enrolls their devices to your UEM.
  4. Your customer installs and launches the Knox E-FOTA client on their fleet of devices. For more information about this, see Install and launch the Knox E-FOTA client.
  5. Your customer’s devices are now enrolled to Knox E-FOTA.

Install and launch the Knox E-FOTA client

To manage devices with Knox E-FOTA, your customer must install the Knox E-FOTA client on their fleet of devices with one of these methods.

Knox E-FOTA client package name

Name Package name Remark
Knox E-FOTA com.samsung.android.knox.efota Common Knox E-FOTA client app package.
com.samsung.android.knox.core.efota

Knox E-FOTA client app package for Samsung legacy OneUI core devices.

See list of Legacy OneUI core devices
Knox E-FOTA plugin com.samsung.android.knox.efota.plugin The package that gets the device admin permission and sets a device policy. The package is installed during enrollment.

Unenroll devices

Unenrolled devices will remain on Knox E-FOTA but won’t consume a license seat. Use POST /devices/bulkUnenroll to provide this functionality on your UEM portal.

Here is a Java code sample that unenrolls a list of devices from Knox E-FOTA:

private HttpResponse<String> bulkUnenroll(String accessToken) throws URISyntaxException, IOException, InterruptedException {
    String bulkUnenrollUrl = API_URI + "devices/bulkUnenroll";
    String body = "{\n" +
            "\"deviceIds\": [\"imei\",\"sn\"]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(bulkUnenrollUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "transactionId": "T882582188b10", "code": "00000", "message": "SUCCESS", "data": {"operationId": "64ff499184509e67e8ac736b", "deviceCount": 2 } }

Subscribe to the KE_DEVICE_BULK_LICENSE_UNENROLL event on Knox Webhook Notification to receive webhook notifications when devices are unenrolled from Knox E-FOTA.

For more information, see the Knox Webhook Notification API reference.

Here is a Java code sample that subscribes to the Knox E-FOTA device unenroll event on Knox Webhook Notification.

private HttpResponse<String> createBulkUnenrollSubscription(String callbackUrl) throws URISyntaxException, IOException, InterruptedException {
    String subscriptionUrl = WEBHOOK_URI + "subscriptions";
    String body = "{\n" +
            "\"url\": " + callbackUrl + ",\n" +
            "\"events\": [\n" +
            "\"KE_DEVICE_BULK_LICENSE_UNENROLL\"\n" +
            "]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(subscriptionUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "payload": { "id": "636c1a692d0f427ee1f07470", "url": "https://some.domain/kwn-results", "events": [ “KE_DEVICE_BULK_LICENSE_UNENROLL” ] }}

Delete devices

Deleting devices from Knox E-FOTA will release their license seats and remove all associated device information from Knox E-FOTA. Use POST /devices/bulkDelete to provide device deletion functionality on your UEM portal.

private HttpResponse<String> bulkDelete(String accessToken) throws URISyntaxException, IOException, InterruptedException {
    String bulkDeleteUrl = API_URI + "devices/bulkDelete";
    String body = "{\n" +
            "\"deviceIds\": [\"imei\",\"sn\"]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(bulkDeleteUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "transactionId": "T882582188b10", "code": "00000", "message": "SUCCESS", "data": { "operationId": "64ff499184509e67e8ac736b", "devicesToProcessCount": 2 } }

Subscribe to the KE_DEVICE_BULK_DELETE event on Knox Webhook Notification to receive webhook notifications when devices are deleted from Knox E-FOTA.

For more information, see the Knox Webhook Notification API reference.

Here is a Java code sample that subscribes to this event on Knox Webhook Notification:

private HttpResponse<String> createBulkDeleteSubscription(String callbackUrl) throws URISyntaxException, IOException, InterruptedException {
    String subscriptionUrl = WEBHOOK_URI + "subscriptions";
    String body = "{\n" +
            "\"url\": " + callbackUrl + ",\n" +
            "\"events\": [\n" +
            "\"KE_DEVICE_BULK_DELETE\"\n" +
            "]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(subscriptionUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "payload": { "id": "636c1a692d0f427ee1f07470", "url": "https://some.domain/kwn-results", "events": [
" KE_DEVICE_BULK_DELETE" ] } }

Get list of devices

Retrieve a list of devices on Knox E-FOTA. This operation has filtering parameters, which you can use to allow your customers to filter their Knox E-FOTA device list.

Use POST /devices/getDevices to retrieve a list of devices, and allow your customers to define filters with the provided filter parameters.

Here is a Java code sample that gets a list of devices: 

private HttpResponse<String> getDevices(String accessToken) throws URISyntaxException, IOException, InterruptedException {
    String getDevicesUrl = API_URI + "devices/getDevices";
    String body = "{\n" +
            "\"deviceIds\": [\"imei\",\"sn\"]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(getDevicesUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{"transactionId": "T882582188b10", "code": "00000", "message": "SUCCESS", "data": {...}}

POST /devices/getDevices only returns devices uploaded using the Knox E-FOTA API. Devices uploaded through the Knox E-FOTA console are not returned by this operation.

However, the following operations will return information about all devices uploaded to your customer’s Knox E-FOTA device pool, including devices that were not uploaded using the Knox E-FOTA API.

Knox E-FOTA client Privacy policy

When the Knox E-FOTA client is installed and launched on your customer’s devices, it shows the device user a privacy policy agreement. Your customer might not want to prompt their device users with this agreement to streamline the device setup process. The Knox E-FOTA API provides functionality to skip the privacy policy agreement so devices can enroll to Knox E-FOTA without any manual interaction needed.

Use PUT /privacyPolicy to let your customer configure the “skip privacy policy” setting. You can also get the current configuration for this setting with GET /privacyPolicy.

Next step

Next, we’ll cover how to manage campaigns and firmware on Knox E-FOTA.

Campaigns and firmware

On this page

Is this page helpful?