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 the following section 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. On 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: Set up authentication

Knox Mobile Enrollment supports both Knox Cloud Authentication and Knox OAuth 2.0 Authentication. Once you register for a Samsung Knox account to use the Knox Mobile Enrollment console, see the appropriate steps depending on which authentication scheme you’re using.

Knox Cloud Authentication

1. Request access to the Knox cloud services APIs.

   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.

2. Generate your unique Client Identifier and download your key pair from the Knox Cloud API portal.

   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.

3. Create your access token.

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

   For security reasons, the access token has an expiry of 30 minutes. Regenerate as specified in the Knox Cloud APIs integration guide.

Once you’ve generated an access token, you can now use Knox Mobile Enrollment APIs.

Knox OAuth 2.0 Authentication

1. Before you begin, get access to the Cloud Apps menu.

2. Register your app and generate a client ID and client secret.

3. Generate your access token. The instructions differ depending on whether you’re a UEM partner, customer, or a Managed Service Provider (MSP).

   • For UEM partners, see Get access and refresh tokens.
   • For customers and MSPs, see Get access token.

Once you’ve generated an access token, you can now use Knox Mobile Enrollment APIs.

Step 3: 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.

   The header parameter will vary based on the authentication method you’re using. See Header parameter for more details.

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

   GET /kcs/v1/kme/profiles/status?customerId= HTTP/1.1
   Host: https://us-kcs-api.samsungknox.com
   Content-Type:application/json
   

   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
   

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
   

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
   

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
   

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

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.