Tutorial — Knox Deployment Program (KDP) Integration

The aim of this integration is to be able to upload customer devices that are sold through [CARRIER COMPANY] with their customer-side Samsung Knox services, such as Knox Mobile Enrollment and Knox Configure.

Step 1: Sign up for prerequisites

Before proceeding, you must apply and be approved for the Knox Partner Program and the Knox Deployment Program. To learn more, see Get access to the Reseller Portal.

Step 2: Request access to the Cloud Apps feature

To request access to the Cloud Apps menu on the navigation pane of Knox Developer Portal, send an email to knoxapi@samsungknox.com with subject ‘Cloud Apps feature’. Include the following details in your email:

• Company name
• Country
• Email address associated with your Samsung Knox account.
• Your intention to access KDP APIs for cloud apps.
• Description of your use cases.

You can also create a Support ticket.

Step 3: Generate and test your access token

After you get access to the Cloud Apps feature:

1. Go to the Knox Developer Portal.

   • You can also access the Knox Developer Portal through the Knox Partner Portal by clicking Knox Developers on the navigation pane.

2. Register your app to get its client ID and client secret.

3. Generate an access token using the client ID and client secret. This access token is sent in the header of the Knox Deployment Program API request.

4. Ensure that your access token is correctly configured by making a test call to any operation in Knox Deployment Program API.

Step 4: Integrate with the Knox Deployment Program API

Here are some common Knox Deployment Program API operations.

Some Knox Deployment Program operations involve performing an action on a customer account. To test these endpoints, you’ll need a separate Samsung Knox customer account. For more details, see Create a Samsung Knox account.

Upload devices

Upload devices to your customer’s account with PUT /kcs/v1/rp/devices/upload.

In the header, include your signed access token from the previous step. Then, make sure you include the following required body parameters:

• customerId – ID of the customer to upload devices for.
• resellerId – Your reseller ID.
• transactionId – Unique transaction ID for this operation. You can later use this transaction ID to check the status of this operation.
• devices - An array of device IMEIs or Serial Numbers to be uploaded.
• type - Device type. IMEI, MEID, or SN.

There are also optional parameters you can set for this request. To learn more, see the Knox Deployment Program API reference.

Here’s a cURL request example that calls the upload operation.

curl --request PUT \
  --url https://api.samsungknox.com/kcs/v1/rp/devices/upload \
  --header 'Authorization: Bearer kz06....L09Wc' \
  --header 'content-type: application/json' \
  --data '{
  "customerId": "string",
  "resellerId": "string",
  "transactionId": "string",
  "devices": [
    "string"
  ],
  "type": "string"
}'

List device transactions status

Get a list of device transaction statuses with GET /kcs/v1/rp/devices/status.

In the header, include your signed access token from the previous step. Then, make sure you include the resellerId as a query parameter in your request.

There are also optional query parameters you can set for filtering. To learn more, see the Knox Deployment Program API reference.

Here’s a cURL request example that calls this operation.

curl --request GET \
  --url https://api.samsungknox.com/kcs/v1/rp/devices?resellerId="your-reseller-id" \
  --header 'Authorization: Bearer kz06....L09Wc'

Delete devices

Delete devices with PUT /kcs/v1/rp/devices/delete.

In the header, include your signed access token from the previous step. Then, make sure you include the following required body parameters:

• customerId – ID of the customer to delete devices for.
• resellerId – Your reseller ID.
• transactionId – Unique transaction ID for this operation. You can later use this transaction ID to check the status of this operation.
• devices - An array of device IMEIs or Serial Numbers to be deleted. Required if removeTransactionId is not provided.
• removeTransactionId - Transaction ID of a device upload operation. Allows you to delete devices from that specific upload. Required if devices is not provided.
• type - Device type. IMEI, MEID, or SN. Required if devices is provided and removeTransactionId is not provided.

There are also optional parameters you can set for this request. To learn more, see the Knox Deployment Program API reference.

curl --request PUT \
  --url https://api.samsungknox.com/kcs/v1/rp/devices/delete \ 
  --header 'Authorization: Bearer kz06....L09Wc' \ 
  --header 'content-type: application/json' \ 
  --data '{ 
  "customerId": "string",
  "resellerId": "string", 
  "transactionId": "string", 
  "devices": [ 
    "string" 
    ]
  }'

List devices

Get a list of devices uploaded with GET /kcs/v1/rp/devices.

In the header, include your signed access token from the previous step. Then, make sure you include the resellerId as a query parameter in your request.

There are also optional query parameters you can set for filtering. To learn more, see the Knox Deployment Program API reference.

Here’s a cURL request example that calls this operation.

curl --request GET \
  --url https://api.samsungknox.com/kcs/v1/rp/devices?resellerId="your-reseller-id" \
  --header 'Authorization: Bearer kz06....L09Wc'

List customers

Get a list of customers with GET /kcs/v1/rp/customers/list.

In the header, include your signed access token from the previous step. Then, make sure you include the resellerId as a query parameter in your request.

There are also optional query parameters you can set for filtering. To learn more, see the Knox Deployment Program API reference.

curl --request GET \
  --url https://api.samsungknox.com/kcs/v1/rp/customers/list?resellerId="your-reseller-id" \
  --header 'Authorization: Bearer kz06....L09Wc'

Other API operations

Evaluate any additional operations which you might wish to integrate. For more information, see the Knox Deployment Program API reference.

As a participating Knox Deployment Program reseller, you are responsible for uploading devices purchased by your customers for access to Knox Mobile Enrollment, Knox Configure, and other Knox cloud services. The association between the reseller and the customer is automatically created during a device’s first upload based on their customerId.