Get started

This guide provides step-by-step instructions to integrate Knox Asset Intelligence API capabilities into your web services.

Before you begin

Before you start the integration process, ensure you have the following:

• A valid Samsung Knox account with Knox Asset Intelligence enabled
• Familiarity with REST APIs and authentication mechanisms
• A development environment capable of making HTTP requests
• Devices enrolled in Knox Asset Intelligence

Step 1 — Request API access

• OAuth 2.0
• Legacy authentication

Step 2 — Generate an access token

• OAuth 2.0
• Legacy authentication

Step 3 — Verify your integration

Make a test call to any Knox Asset Intelligence API endpoint to ensure your integration was successful. For example, try retrieving device information. For more examples and use cases, see Tutorials.

• OAuth 2.0
• Legacy authentication

curl --location 'https://api.samsungknox.com/kai/v1/devices/getDevices' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}' \
     --data '{
         "pageNum": 0,
         "pageSize": 1
     }'

{
  "code": "2000000",
  "message": "SUCCESS",
  "pageNum": 0,
  "pageSize": 1,
  "totalCount": 1,
  "totalPages": 1,
  "size": 1,
  "devices": [
    {
      "id": "device123",
      "imei": "123456789012345",
      "model": "SM-G991U",
      "status": "ACTIVE",
      "lastUpdated": "2023-01-15T10:30:00Z"
    }
  ]
}

curl --location 'https://us-kcs-api.samsungknox.com/kcs/v1/kai/devices' \
     --header 'x-knox-apitoken: {AUTH_TOKEN}'

{
  "code": "2000000",
  "message": "SUCCESS",
  "devices": [
    {
      "id": "device123",
      "imei": "123456789012345",
      "model": "SM-G991U",
      "status": "ACTIVE"
    }
  ]
}

Troubleshooting

If you encounter issues with your integration, check these common problems:

1. Authentication errors: Verify that your access token is valid and properly formatted in the Authorization header. Ensure that the token hasn’t expired, and that it was generated with the correct client credentials. Use tools like cURL to test your authentication.
2. Permission errors: Make sure your application has the required kai scopes (for OAuth 2.0 integrations) or equivalent permissions (for legacy authentication integrations) for the operations you’re trying to perform.
3. Invalid parameters: Ensure all required parameters are provided in the correct format according to the API reference. Review error messages returned by the API for specific details on what might be wrong. Make sure you are using the correct customer ID for your company account.
4. Network issues: Verify that your network connection is stable and that there are no firewall restrictions blocking API requests. Test connectivity to the API endpoint, and confirm that your requests are not being blocked by corporate firewalls or proxies.
5. Rate limit exceeded: The API has a rate limit of 25 requests per second. If you exceed this limit, wait before making additional requests.

If you still need help, create a support ticket. Include detailed information about the error, including the endpoint you were calling, request/response details (with sensitive data redacted), and any error codes received.