Get started

This section describes how to get started on using the Knox Mobile Enrollment APIs.

Step 1: Sign up for Knox Mobile Enrollment

1. Register for a Samsung Knox account as a Knox Mobile Enrollment customer. Follow the steps in these sections to create a Samsung account and a Knox Portal account. If you already have a Knox Mobile Enrollment account, skip this step.

   1. Create a Samsung account

      1. Navigate to the Samsung account creation page. Select SIGN UP NOW. Read through the Terms & Conditions, Terms of Service, and the Samsung Privacy Policy. You must select AGREE to continue.

      2. Fill out all form fields provided. Carefully double-check the options entered before proceeding. Select the NEXT button at the bottom of the page to proceed.

      3. The Samsung account screen displays again, stating you have successfully signed up for a Samsung account. Select DONE once you have reviewed the contents of the screen and look for the email sent to your provided email address to activate your Samsung account.

   2. Create a Knox Portal account.

      1. Navigate to the Knox Mobile Enrollment page and select APPLY NOW.

      2. Complete the required fields within the Apply for Knox Mobile Enrollment screen. Refer to the TERMS AND CONDITIONS field (at the bottom of the screen) and agree to the required terms (*) to enable the APPLY button and successfully proceed with your Samsung account application.

      3. You will receive an email to confirm your request. Click Complete Registration to continue.

2. Enter and confirm your Knox web portal password. Wait to be approved by Samsung, which can take up to several business days.

3. In your Samsung Knox dashboard, select LAUNCH CONSOLE within the Knox Mobile Enrollment field to open the Knox Mobile Enrollment portal console.

4. Find your customerId by clicking your profile settings at the top right of the main dashboard or finding it in the Resellers tab of the Knox Mobile Enrollment portal.

Step 2: Request access to the Knox Cloud APIs service

Apply for Knox Cloud API access to the cloud REST service by contacting your local Samsung representative or raising a support ticket. This provides portal access to the Knox Cloud APIs to generate the authentication token sent in the header of a request. For more information, see the Knox Cloud APIs integration guide.

Step 3: Generate your unique Client Identifier and download your key pair from the portal, Knox Cloud APIs

Download your unique key pair and clientIdentifier from the Knox Cloud APIs. The clientIdentifier can be re-generated through the console, but must be bound to the downloaded certificate, as described in the Knox Cloud APIs integration guide.

Step 4: Create your access token

Call the access token REST API to generate your access token x-knox-apitoken.

Step 5: Assign device profiles

1. As a customer, you create profiles for your devices using the Create Profile Async API. It is recommended to use this API instead of Create Profile because for some MDM APKs, it might take a long time to download. When using the Create Profile Async API, use the List Profile Transaction Status API to query the profile status.

    POST /kcs/v1/kme/profiles/createAsync HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken:
   
    GET /kcs/v1/kme/profiles/status?customerId= HTTP/1.1
    Host: https://us-kcs-api.samsungknox.com
    Content-Type:application/json
    x-knox-apitoken:
   

   If you want to instead create profiles synchronously, use the Create Profile API.

     POST /kcs/v1/kme/profiles/create HTTP/1.1
     host: https://us-kcs-api.samsungknox.com
     content-type:application/json
     x-knox-apitoken:
   

2. Once a reseller uploads your devices to Samsung servers, you can see the upload by calling Get Device Uploads API.

    GET /kcs/v1/kme/devices/uploads/list HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken:
   

3. Call the Approve Upload API to approve a reseller’s upload. If you set auto approval to true for a specified reseller, uploaded devices will be automatically approved.

    POST /kcs/v1/kme/devices/uploads/approvals HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken:
   

4. Before assigning a profile to your devices, you need to encrypt device user’s userName and userToken.

   1. Download the Samsung Knox Cloud JAR file and README.md file.

      This solution is designed for a Java environment (v1.6 and above).

   2. To encrypt text, use the KnoxEncryptionUtility class of the JAR file. Instantiate the class, then pass the text to be encrypted to encrypt(String text) method. This method will return the corresponding encrypted text.

       KnoxEncryptionUtility knoxEncryptionUtil = new KnoxEncryptionUtility();
       String encryptedText = knoxEncryptionUtil.encrypt();
      

5. Assign your profiles to your devices using the Assign Profile API.

    PUT /kcs/v1/kme/devices/assignProfile HTTP/1.1
    host: https://us-kcs-api.samsungknox.com
    content-type:application/json
    x-knox-apitoken:
   

Server URL

Select a server to use based on the region of the devices that are being resold. Your API requests will be sent to this server.

Header parameter

x-knox-apitoken

This required authentication key is used to verify requests and identify accounts. Follow the steps in the Knox Cloud APIs integration guide guide to generate one.

Common parameters

Pagination

REST APIs that return a list of objects use the following paginated syntax. The Knox Deployment Program supports result paging, and it is controlled with the following attributes.

{
  "pageNum" : 0,
  "pageSize" : 100
}

This will specify how many results are returned. If the results do not fit onto a single page, resubmit the query (pageNum="1", pageNum="2", etc.). pageNum begins indexing from 0 (default value). pageSize has a default value of 100.

Other common parameters

The following attributes are unique identifiers that specify the different parties in a request, and the request itself.