Migrating from Knox Deployment Program Gen1 APIs to Gen2

This guide covers how to migrate from the Knox Deployment Program Gen1 API to Gen2, which is the latest generation. The Gen2 API features restructured endpoints to simplify your workflow and enhance security.

About Gen1 and Gen2 APIs

The Knox Deployment Program Gen1 API was launched in late 2017. This was the initial release with a limited number of endpoints and basic authentication.

In Gen2, the API has been significantly restructured to simplify your workflow, and also supports OAuth 2.0 authentication. The Gen1 static API authentication key X-WSM-API-TOKEN has been replaced with an Authorization token in Gen2, which is much more secure.

For more details, refer to Release notes and Comparing Gen2 and Gen1 Knox Deployment Program APIs.

Server URL change

For the migration, the following Gen1 API servers must be whitelisted in your network firewall:

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

To the following server will be used instead for Gen2, which also needs to be whitelisted in your firewall:

• https://api.samsungknox.com/kcs/v1/rp (global server)

During migration or 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"
        }]
      }
    }