Knox Manage Open API

Download OpenAPI specification:Download

INTRODUCTION

Welcome to the reference for the Knox Manage Open API. To learn about the common use cases of the Knox Manage Open API, check out the API Guides.

The Knox Manage Open API provides a broad set of operations and resources that:

  • User, device, organization, group management
  • Apply policies to users, groups, organizations, and devices
  • User authentication, etc.

Refer to the Open API List for all supported API types and descriptions.

New Features

When the Knox Manager product is released, new Open APIs are also released. Check out Knox Manage's Release Note.

Authentication

OAuth 2.0

Knox Manage recommends you to create a dedicated API user with API write access on a tenant when authenticating via OAuth, and then create an OAuth client for this user. See Create an API User for how to do this. By creating a dedicated API user, you can control permissions of the API user without affecting other non-API users.

If a user is deactivated, all of the user's OAuth clients will be automatically deactivated.

Authenticating via OAuth requires the following steps:

  1. Create a Client
  2. Generate a Token
  3. Make Authenticated Requests (Bearer Authentication)

Create a Client

You must first create an OAuth client in Admin Portal UI of the Knox Manager. To do this, you must be an administrator of your Knox Manage tenant. This is a one-time operation. You will be provided with a Client ID and a Client Secret. Please refer to the Manage API clients, as it will be required for the next step.

Generate a Token

After creating a client, you must make a call to obtain a bearer token using the Generate an OAuth token operation. This operation requires the following parameters:

  • client_id - the Client ID displayed when you created the OAuth client in the previous step.
  • client_secret - the Client Secret displayed when you created the OAuth client in the previous step
  • grant_type - must be set to client_credentials

Token Request URL

https://{Your Region}.manage.samsungknox.com/emm/oauth/token

Request Sample

curl -X POST \
  https://ap01.manage.samsungknox.com/emm/oauth/token \
  -d "grant_type=client_credentials&client_id=APItest@km.com&client_secret=APItestpassword" \
  -H "Content-Type: application/x-www-form-urlencoded"

Response Sample

{
    "access_token": "98bfa733-aa70-4491-931f-f35442ff2e7e",
    "token_type": "bearer",
    "expires_in": 997331046,
    "scope": "read"
}

*Note: The Client ID and Client Secret mentioned above were displayed when you created the OAuth Client in the prior step. The Generate an OAuth token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call Generate an OAuth token again to generate a new one.

Bearer Authentication

To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:

  • Authorization: Bearer{bearer_token}

User Authentication

Open API related to authentication of Knox Manager users. If the user type in Knox Manager is specified as LDAP user, it sends an authentication request to the connected LDAP.

Authentication

Authentication is performed by receiving the Knox Manager user ID and password. It is only for Tenant users for whom Client ID is issued.

Authorizations:
Request Body schema: application/x-www-form-urlencoded
userId
required
string <= 50 characters /[^A-Z|a-z|0-9|\_|\:|\.|\-|\+]/

User ID, unique user ID.
The field allows only English alphabet, numbers and '_, :, ., -, +'.

userPassword
required
string <= 50 characters /^.{8,30}$/, /[0-9]+/, /[a-zA-Z]+/, /[^0-9a-z...

User Password.
Passwords must be between 8 and 30 characters.
Passwords must contain at least one number.
Passwords must contain at least one letter.
Passwords must contain at least one special character.

Responses

Request samples

curl -X POST \
    https://ap01.manage.samsungknox.com/emm/oapi/auth/authenticate \
    -H "cache-control: no-cache" \
    -H "content-type: application/x-www-form-urlencoded" \
    -H "Authorization: bearer98bfa733-aa70-4491-931f-f35442ff2e7e" \
    -d "userId=kmuser&userPassword=kmuserpassword" 
 

Response samples

Content type
application/json
{
  • "resultCode": "0",
  • "resultMessage": "No Error",
  • "resultValue": {
    }
}

Device

Get Device List

This API is to query the Device Information List.

Authorizations:
Request Body schema: application/x-www-form-urlencoded
start
integer <int32>
Default: 0

Page indexing begins from 0 (pageNum >= 0)

limit
integer <int32>
Default: 1000

Records per page (0 < pageSize <= 1000)

userId
string <= 50 characters /[^A-Z|a-z|0-9|\_|\:|\.|\-|\+]/

User ID, unique user ID.

deviceStatus
string

Device Status (I : Deactivated, P : Provisioned, A : Activated, B : Blocked, BS : Blocked(System), BA : Blocked(Admin), BL : License Expired). It is case sensitive.

Responses

Request samples

curl -X POST \
    https://ap01.manage.samsungknox.com/emm/oapi/device/selectDeviceList \
    -H "cache-control: no-cache" \
    -H "content-type: application/x-www-form-urlencoded" \
    -H "Authorization: bearer98bfa733-aa70-4491-931f-f35442ff2e7e" \
    -d "deviceStatus=A" 
 

Response samples

Content type
application/json
{
  • "resultCode": "0",
  • "resultMessage": "No Error",
  • "resultValue": {