Menu

Migrating from KDP Gen1 APIs to Gen2

The Knox Deployment Program (KDP) is designed for Samsung device resellers, including carriers and distributors, who purchase devices on behalf of enterprise customers. KDP is the underlying backbone of Samsung’s Knox Mobile Enrollment, Knox Configure, and other Knox cloud services, as it supplies information about enterprise devices to other services.

This guide shows how to migrate from KDP REST APIs of the 1st generation (GEN1) to the 2nd generation (GEN2). In GEN2, the latest generation, the KDP APIs have been restructured to simplify your workflow and enhance API authentication security.

Audience

This guide is intended for web developers working for Samsung device resellers, who purchase devices on behalf of enterprise customers and use their own websites to identify which customers own the devices.

Introduction

KDP Gen1 APIs were launched in late 2017; this was the initial release with a number of APIs and basic authentication.

In KDP APIs Gen2, the KDP APIs have been restructured to simplify your workflow and enhance API authentication security. The Gen1 static API authentication key X-WSM-API-TOKEN 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.

For more detail about the API changes, see What's New in KDP Gen2 and Comparing Gen2 and Gen1 KDP APIs.

Server URL change

We will migrate from the following Gen1 API servers, which must be whitelisted in your network firewall as required:

To the following Gen2 API servers, which should also be whitelisted as required:

During migration/development, please use the new Gen2 server URL to test the APIs.

You can stop using the Gen1 server URL once your Gen2 solution is live.

Request for the KDP API access

When you’re using Gen1 APIs, your reseller portal dashboard has a reseller API key section, as shown below. This static API key is for API usage.

In order to use the Gen2 API, please apply for KDP API access & get your access Key pair. Follow this tutorial for detailed instructions (Step 2).

Once KDP API access is approved, your reseller portal dashboard will show a Knox Cloud API section

API message payload and response format changes

For overall mapping of the Gen1 API to Gen2, please read the REST API Comparison section in this article.

Below are the differences in message payload & response format.

For Upload/Delete Devices:

  • V1 message:
    {
      "transactionId": "244303",
      "resellerId": "4680000925",
      "customerId": "123004321",
      "transactionType": "New",
      "devices": {
        "type": "IMEI",
        "list": ["351800000675702"
        ]
      }
    }
  • V2 message:
    {
      "transactionId": "244303",
      "resellerId": "4600000925",
      "customerId": "123400321",
      "type": "IMEI",
      "devices": [
        "351826100005702"
      ]
    }

transactionType has been removed (now identified by endpoint) and type has been moved to a different level.

For List Devices:

  • V1 message:
    {
      "totalCount": 0,
      "totalPage": 0,
      "pageNum": 0,
      "devices": [{
        "imei": "357192611111112"
      }]
    }
  • V2 message:
    {
      "code": "2000000",
      "message": "SUCCESS",
      "pageNum": 0,
      "pageSize": 1000000,
      "totalCount": 0,
      "totalPages": 0,
        "size": 0,
        "devices": [{
          "id": "6012afe85f18342e67ee9126",
          "createTime": 1611837416372,
          "mei": "351826000675702",
          "customerName": "TOP Oil",
          "customerId": "4600001586",
          "serialNumber": "R3OOO00WKLD",
          "meid": "089077500000423280",
          "model": "SM-G981B/DS",
          "state": "Verified",
          "uploadId": "ddb71b6c-3aef-4d54-b1f4-b86480aa447d"
        }]
    }

Element totalPage was changed to totalPages and new elements were added.

For Check Transaction status message

  • V1 message:
    {
      "totalCount": 2,
      "totalPage": 1,
      "pageNum": 0,
      "transactions": [{
        "transactionId": "7500657464",
        "state": "Complete",
        "type": "Put",
        "devices": [{
          "imei": "807212627606673"
        }, {
          "imei": "21975175979444"
        }, {
          "imei": "40649504931126",
          "code": 4092100,
          "message": "RESELLER_DEVICE_ALREADY_EXISTS",
          "data": "device imei[097436145498341] already exists"
        }]
      }]
    }
  • V2 message:
    • Whole message is surrounded by devices element not present earlier:
      {
        "devices": {
          "totalCount": 1,
          "totalPage": 1,
          "pageNum": 0,
          "transactions": [{
            "transactionId": "246903",
            "state": "Complete",
            "type": "Put",
            "operationType": "UPLOAD",
            "devices": [{
              "imei": "351826110675643",
              "code": 40000004,
              "message": "DEVICE_INVALID",
              "data": "The specified device is not valid."
            }]
          }]
        }
      }
    • Internal element devices contain information about only failed transaction of all the devices in the transaction. If transaction went all fine, this element will be missing:

      {
        "devices": {
          "totalCount": 1,
          "totalPage": 1,
          "pageNum": 0,
          "transactions": [{
            "transactionId": "248603",
            "state": "Complete",
            "type": "Put",
            "operationType": "UPLOAD"
          }]
        }
      }
Share it: