Tutorial — Knox Deployment Program (Knox Deployment Program) 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.

Prerequisites and Documentation (General Steps)

1. Creating a Knox Deployment Program (Knox Deployment Program) account
2. Applying for Knox Deployment Program API access and getting your Access Key Pair
3. Ensuring you can generate session tokens (requires coding)
4. Create your access token
5. Integrating with the Knox Deployment Program APIs (requires coding)
6. Testing your Knox Deployment Program API Integration
7. Integrating your Knox Deployment Program integration with your internal systems
8. Go Live with your Knox Deployment Program API Integration

Step 1: Sign up for the Knox Deployment Program

1. Get access to the Reseller Portal.

2. Login to your account through the Knox Deployment Program Portal within the Samsung Knox dashboard.

3. Select LAUNCH CONSOLE to open the Knox Deployment Program Portal console.

4. Find your resellerId in the main dashboard of the console.

5. As soon as you apply, please email the [SALES ENGINEER] to let them know that the application has taken place.

   • Please provide the Samsung account (email address) that you have used to apply.
   • This will fast-track your application.

Step 2: Apply for Knox Deployment Program API access and getting your Access Key Pair

As soon as you get your Knox Deployment Program account, log into the Samsung Knox Resellers page.

• Click on Apply for Knox Deployment Program API access.

• Please email the [SALES ENGINEER] to let them know.

  • Alternatively, you can apply for Knox Cloud API access to the cloud REST service by contacting your local Samsung representative or raise a support ticket.

• Once you receive your API access approval, log into the Samsung Knox Resellers page.

• Download your Key pair and generate your clientIdentifier from the Knox Cloud APIs by following Steps 1, 2, and 3 of the Knox Cloud Authentication Developer Guide.

  • The clientIdentifier can be re-generated through the console, but must be bound to the downloaded certificate, as described in the Knox Web Services overview.

For more information, see the Knox Web Services overview.

Step 3: Generate and sign your access token

Follow steps 4 to 9 of the Knox Cloud Authentication Developer Guide to generate and sign your access token.

Step 4: Integrate with the Knox Deployment Program API

Here are the most important Knox Deployment Program API operations to integrate with:

Upload devices

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

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 -X PUT \
  https://us-kcs-api.samsungknox.com/kcs/v1/rp/devices/upload \
  -H 'content-type: application/json' \
  -H 'x-knox-apitoken: <insert-token-here>' \
  -d '{
  "customerId": "string",
  "resellerId": "string",
  "transactionId": "string",
  "devices": [
    "string"
    ]
  "type": "IMEI"
  }'

List device transactions status

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

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 -X GET \
  https://us-kcs-api.samsungknox.com/kcs/v1/rp/devices/status?resellerId="your-reseller-id" \
  -H 'x-knox-apitoken: <insert-token-here>'

Delete devices

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

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 -X PUT \
  https://us-kcs-api.samsungknox.com/kcs/v1/rp/devices/delete \
  -H 'Content-Type: application/json' \
  -H 'x-knox-apitoken: <insert-token-here>' \
  -d '{
  "customerId": "string",
  "resellerId": "string",
  "transactionId": "string",
  "devices": [
    "string"
  ],
  "removeTransactionId": "string",
  "type": "string",
  "vendorId": "string"
}'

List devices

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

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 -X GET \
  https://us-kcs-api.samsungknox.com/kcs/v1/rp/devices?resellerId="your-reseller-id" \
  -H 'x-knox-apitoken: <insert-token-here>'

List customers

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

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 -X GET \
  https://us-kcs-api.samsungknox.com/kcs/v1/rp/customers/list?resellerId="<your-reseller-id> \
  -H 'x-knox-apitoken: <insert-token-here>'

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.

Step 5: Test your Knox Deployment Program API Integration

Since you are testing as a Samsung Device Vendor, you will need a Samsung Knox Customer-Side Knox Mobile Enrollment account for testing the end-to-end flow.

Create a different Knox Portal account than the account used on Step 1 above.

• Head to the Samsung Knox Customers page.
• Click Enroll (top, right-hand side).
• This application button will have you create a Samsung Account.
• This means that you will temporarily be taken to account.samsung.com where you can create a Samsung account with a test email address.
  1. You can use any email address that is not from a free email provider (that is, use a business email address).
  2. The Samsung Account will serve as the Single Sign On for the Knox Portal.
• Once you create the Samsung Account, you will be re-routed back to the main Knox Portal and will have access.

Get Knox Mobile Enrollment access for your newly-created test account.

• Once you are inside the Knox Portal, go to Knox Suite > Knox Mobile Enrollment and request access.

Ensure that you can upload and delete devices against a (test) customer-side Samsung Knox Customer account.

Step 6: Integrate your Knox Deployment Program integration with your internal systems

The effort and duration of this project stage is dependent on your integration resources, technical availability and internal system complexity.

Step 7: Go Live with your Knox Deployment Program API Integration

Once all your internal and Knox Deployment Program API integration testing is complete, you are ready to go live with your Knox Deployment Program integration and to upload devices to customer’s environments.

Coordinate with your Samsung representative on go-live steps.