Migrating from Gen1 to the Gen2 API

This guide covers the differences between the legacy Gen1 API and the latest Gen2 API for Knox Deployment Program, and helps facilitate a smooth migration to Gen2. Compared to Gen1, the Gen2 API features streamlined device provisioning flows (unified endpoints for single-tier and two-tier provisioning), improved error handling, and enhanced authentication security.

Before you begin

1. Before starting the migration process, make sure you can sign in to your Knox Developer account.

   • If you aren’t sure if you have access, or get a “You don’t have access” error when you try to sign in, ask the super admin of your KDP tenant sign in first and then try again.

2. Once you are signed in, verify that you can view the Cloud Apps menu on the navigation pane of Knox Developer portal.

   • If you’re unable to view the Cloud Apps menu or need assistance, create a Support ticket with the subject line “KDP Gen1 API migration”. Make sure to provide your company name, resller ID, and a brief description of the issue you’re facing.

Authentication changes

The legacy Gen1 API uses an X-WSM-API-TOKEN to authenticate your calls. The Gen2 API leverages Knox OAuth 2.0 Authentication, using an Authorization bearer token for call authentication.

Proceed to:

1. Register a Cloud App to get its client ID and secret.

2. Generate an access token

Base URL differences

The Gen1 API is accessed through regional servers:

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

The Gen2 API uses a different server URL — ensure the Gen2 global server URL is included in your firewall exceptions:

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

Endpoint comparison

The following table shows how existing Gen1 API endpoints map to Gen2:

The Retrieve reseller details Gen1 feature (POST /bulkenroll/v1/reseller/resellers) isn’t relevant to most distributors, resellers, and carriers, and therefore isn’t supported in Gen2. If you are currently using this functionality, please create a support ticket for migration assistance.

The Retrieve KME profile aliases Gen2 feature (GET /kcs/v1/rp/profilealias/kme) is a new endpoint that allows you to retrieve a list of Knox Mobile Enrollment (KME) profile aliases associated with your reseller ID. When uploading customer devices, you can include the KME profile alias associated with that customer.

API payload and format comparison

The following sections highlight key changes between commonly used Gen1 and Gen2 API calls.

Upload devices

For details on uploading devices using the Gen2 API, see Upload devices.

Request body

The Gen1 payload has a transactionType field which is not supported for Gen2. On the other hand, the Gen2 payload has a profileAliases array which is not supported for Gen1. Each profileAlias Gen2 object includes the name of the profile alias and the service ID.

{
  “transactionId”: “transaction123”,
  “resellerId”: “1111111”,
  “customerId”: “2222222”,
  “vendorId”: “3333333”,
  “transactionType”: “New”,
  “orderNo”: “Order123”,
  “orderTime”: 1542405655,
  “devices”: {
    “type”: “IMEI”,
    “list”: [
      “35163899….236”,
      “35163899….123”,
      “35163899….456”
    ]
  }
}

{
  “transactionId”: “transaction123”,
  “resellerId”: “1111111”,
  “customerId”: “2222222”,
  “vendorId”: “3333333”,
  “orderNo”: “ORD34152345”,
  “orderTime”: 1542405655,
  “type”: “IMEI”,
  “devices”: [
    “35163899….236”,
    “35163899….123”,
    “35163899….456”
  ],
  “profileAliases”: [
    {
      “profileAlias”: “profile_a”,
      “serviceId”: “kme_service_id”
    }
  ]
}

Success response

The Gen2 success response always includes the operationType field, indicating an upload operation. The Gen1 response does not include a corresponding field.

{
  “transactionId”: “transaction123”,
  “state”: “Progress”,
  “code”: 2000000,
  “message”: “SUCCESS”
}

{
  “transactionId”: “transaction123”,
  “state”: “Progress”,
  “code”: 2000000,
  “message”: “SUCCESS”,
  “operationType”: “UPLOAD”
}

Error response

The Gen1 error response includes transactionId and state, which don’t appear for Gen2.

{
  “transactionId”: “transaction123”,
  “state”: “Rejected”,
  “code”: 4002101,
  “message”: “RESELLER_ID_MISSING”,
  “data”: “reseller id is missing”
}

{
  “code”: 4010000,
  “message”: “AUTHORIZATION_FAIL”,
  “data”: “Invalid Api Key”
}

Delete devices

For details on deleting devices using the Gen2 API, see Delete devices.

Request body

The Gen1 payload has a transactionType field which is not supported for Gen2.

{
  “transactionId”: “transaction123”,
  “resellerId”: “1111111”,
  “customerId”: “2222222”,
  “vendorId”: “3333333”,
  “transactionType”: “Delete”,
  “devices”: {
    “type”: “IMEI”,
    “list”: [
      “35163899….236”,
      “35163899….123”,
      “35163899….456”
    ]
  }
}

{
  “transactionId”: “transaction123”,
  “resellerId”: “1111111”,
  “customerId”: “2222222”,
  “vendorId”: “3333333”,
  “type”: “IMEI”,
  “devices”: [
    “35163899….236”,
    “35163899….123”,
    “35163899….456”
  ]
}

Success response

The Gen2 success response always includes the operationType field, indicating a delete operation. The Gen1 response does not include a corresponding field.

{
  “transactionId”: “transaction123”,
  “state”: “Progress”,
  “code”: 2000000,
  “message”: “SUCCESS”
}

{
  “transactionId”: “transaction123”,
  “state”: “Progress”,
  “code”: 2000000,
  “message”: “SUCCESS”,
  “operationType”: “DELETE”
}

Error response

The Gen1 error response includes transactionId and state, which don’t appear for Gen2.

{
  “transactionId”: “transaction123”,
  “state”: “Rejected”,
  “code”: 4002101,
  “message”: “RESELLER_ID_MISSING”,
  “data”: “reseller id is missing”
}

{
  “code”: 4010000,
  “message”: “AUTHORIZATION_FAIL”,
  “data”: “Invalid Api Key”
}

Get transaction status

For details on retrieving transcation statuses using the Gen2 API, see List device transaction status.

Mandatory query parameters

Since it’s a GET call, there is no request body for either the Gen1 or Gen2 API. Both APIs have the same mandatory parameter.

Success response

The Gen2 success response always includes the operationType field, which indicates if it was an upload or delete operation. The Gen1 response does not include a corresponding field. For both Gen1 and Gen2 APIs, operation-level error messages for transactions appear within transaction objects.

{
  “totalCount”: 2,
  “totalPage”: 1,
  “pageNum”: 0,
  “transactions”: [
    {
      “transactionId”: “transaction123”,
      “state”: “Complete”,
      “type”: “Put”,
      “devices”: [
        { “imei”: “35163899….236” },
        { “imei”: “35163899….136” }
      ]
    },
    {
      “transactionId”: “transaction456”,
      “state”: “Complete”,
      “type”: “Put”,
      “devices”: [
        { “imei”: “35163899….123” },
        {
          “imei”: “35163899….456”,
          “code”: 4000000,
          “message”: “RESOURCE_INVALID_PARAM”,
          “data”: “This device [35163899….456] invalid”
        }
      ]
    }
  ]
}

{
  “devices”: {
    “totalCount”: 2,
    “totalPage”: 1,
    “pageNum”: 0,
    “transactions”: [
      {
        “transactionId”: “transaction123”,
        “state”: “Complete”,
        “type”: “Put”,
        “operationType”: “UPLOAD”
        
      },
      {
        “transactionId”: “transaction456”,
        “state”: “Complete”,
        “type”: “Put”,
        “operationType”: “UPLOAD”,
        “devices”: [
          {
            “imei”: “35163899….456”,
            “code”: 4000004,
            “message”: “DEVICE_INVALID”,
            “data”: “The specified device is not valid."
          }
        ]
      }
    ]
  }
}

Error response

The Gen1 error response for the call itself includes transactionId and state, which don’t appear for Gen2.

{
  “transactionId”: “transaction123”,
  “state”: “Rejected”,
  “code”: 4002101,
  “message”: “RESELLER_ID_MISSING”,
  “data”: “reseller id is missing”
}

{
  “code”: 4010000,
  “message”: “AUTHORIZATION_FAIL”,
  “data”: “Invalid Api Key”
}

Error codes

Gen1 and Gen2 error codes are different. You will need to make code changes accordingly. For details on Gen2 errors, see Troubleshooting for Knox Deployment Program.