Menu

Comparing Gen2 and Gen1 KDP APIs

The Knox Deployment Program (KDP) APIs allow KDP-participating carriers/resellers to integrate the features found on the KDP Portal with their own systems for verifying the ownership of the devices purchased by their customers using Knox cloud services such as Knox Configure and Knox Mobile Enrollment. The features include uploading and deleting device IDs (IMEIs/serial numbers).

In KDP APIs Gen2, the latest generation, the KDP APIs have been restructured to simplify your workflow and enhance API authentication security.

  • KDP-participating carriers and resellers wishing to integrate the features found on the KDP portal are advised to use the KDP APIs Gen2. You can learn more about them and how to use those calls in the Gen2 integration guide.
  • If you would still like to use the previous generation of the KDP APIs, you can see its Gen1 integration guide. The KDP APIs Gen1 will continue to work and be supported for existing users.
  • Important note: KDP APIs Gen1 are only used for existing resellers who already have the Gen1 static apiKey. Otherwise, if you are not using the static key or you are a new reseller, please use the KDP APIs Gen2. You can move from Gen1 to Gen2 by applying to the Samsung Admin portal, but refrain from combining or interchanging between these two generations.

Authentication

In the KDP APIs Gen1, a static API license key called X-WSM-API-TOKEN is used. Since it is static, it never expires.

In the KDP APIs Gen2, the static API license key has been replaced with an authentication JSON Web Token called X-KNOX-APITOKEN. This token expires every 30 minutes, making it more secure than the Gen1 license key, which never expires. The token consists of a Client Identifier and unique public-private key pair.

To use the Gen2 APIs, follow the instructions in the Knox Cloud Authentication Guide to generate the new authentication token. After generating your new token, you can use it by including it as a header parameter in your HTTP requests.

REST API Comparison

The table bellow illustrates how APIs in the KDP APIs Gen1 map to those in Gen2:

Feature Gen1 Gen2
Upload/Save Devices

PUT /bulkenroll/v1/reseller/devices

Or

PUT /bulkenroll/v2/reseller/devices

PUT /kcs/v1/rp/devices/upload
Delete Devices PUT /bulkenroll/v1/reseller/devices/delete PUT /kcs/v1/rp/devices/delete
Query Transaction Status

GET /bulkenroll/v1/reseller/devices/status

Or

GET /bulkenroll/v2/reseller/devices/status

GET /kcs/v1/rp/devices/status
Retrieve Customer Details POST /bulkenroll/v1/reseller/customers GET /kcs/v1/rp/customers
Retrieve Resellers Details POST /bulkenroll/v1/reseller/resellers NA
Retrieve a List of Devices GET /bulkenroll/v1/reseller/devices GET /kcs/v1/rp/devices

Device Provisioning

In KDP APIs Gen1, two systems of provisioning devices existed: single-tier and two-tier. Different request parameters were used for saving devices and querying transaction status.

Each system had a different use case:

  • Single-tier-A single reseller provisions devices for a customer.
  • Two-tier-A vendor provisions devices for a customer via a distributor. A vendorId must be specified in the request body.

In KDP APIs Gen2, we simplify the workflow such that there is no distinction between tiers. You use the same APIs for either system or use case, with the exception that you provide different request parameters for certain APIs.

Share it: