Migrating from Knox Deployment Program Gen1 APIs to Gen2

The Knox Deployment Program is designed for Samsung device resellers, including carriers and distributors, who purchase devices on behalf of enterprise customers. Knox Deployment Program 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 Knox Deployment Program REST APIs of the 1st generation (GEN1) to the 2nd generation (GEN2). In GEN2, the latest generation, the Knox Deployment Program 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

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

In Knox Deployment Program APIs Gen2, the Knox Deployment Program 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 Release notes in Knox Deployment Program Gen2 and Comparing Gen2 and Gen1 Knox Deployment Program APIs.

Server URL change

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

• https://eu-be-reseller.samsungknox.com (EU server)
• https://us-be-reseller.samsungknox.com (US server)

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

• https://eu-kcs-api.samsungknox.com (EU server)
• https://us-kcs-api.samsungknox.com (US server)

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 Knox Deployment Program 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 Knox Deployment Program API access & get your access Key pair. Follow this tutorial for detailed instructions (Step 2).

Once Knox Deployment Program 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"
        }]
      }
    }