NOTE — If you're a third party portal provider and you'd like to make calls to Knox cloud service on behalf of your customers, see the integration guide for EMMs.

Generate access token

Complete these steps to generate your access token using the Knox Cloud Authentication API and successfully call the Knox cloud Service APIs.

1. Get access to the Knox Cloud API service
   1. Register for a Samsung Knox account.
   2. Log in to your account and apply for a Knox cloud service on your Knox Dashboard.
   3. Apply for Knox Cloud API access by contacting your local Samsung representative.
      • If you can't get access through a Samsung Knox representative, please create a support ticket from the Knox Dashboard to request access.
2. Generate your key pair from the Knox API Portal
   1. Launch the Knox API Portal from the Samsung Knox Dashboard.
   2. From the portal, generate a public/private key pair called "keys.json" by clicking Download. This is a JSON file that contains the following information. It only needs to be generated once:
      • Public key: Key that is sent in the body of the accesstoken REST API and stored by Samsung Knox to validate signed requests.
      • Private key: Key that should be stored and never revealed. This key is used for signing the Client Identifier and the Access Token returned by the REST API call. This key is not stored by Samsung Knox and we will never request it from you.

   * Access to Knox Cloud API Portal is supported by the following browsers: Chrome, Firefox, Safari, and Microsoft Edge. In order to get the best possible Knox Cloud API experience, upgrade your preferred browser to the latest version.

3. Generate your unique Client Identifier from the Knox API Portal. This unique identifier only needs to be generated once, unless either:
   • Privileges need to be changed.
   • The Client Identifier is lost or stolen.

   In both cases, re-generating the Client identifier invalidates the previous one.

   
4. Get the support files
   JavaJavaScript.NET

   This solution is designed for a Java environment (v1.6 and above). Download the .jar and READ ME file

   Download JAR

   $ npm install knox-token-library-js

   Get the NuGet package.

   Download nupkg

5. Sign your Client Identifier with the token utility supplied above. See the source code below on how to sign your Client Identifier. For more information on using this utility jar, refer to the included READ ME file in the .jar file download package.

   Java JavaScript .NET

   String clientId = "myClientId";
   String cert = "src/test/resources/keys.json";
   String signedClientId = KnoxTokenUtility.generateSignedClientIdentifierJWT(new FileInputStream(cert), clientId);
                   

   const knoxTokenLibraryJs = require('knox-token-library-js');
   var clientId = "<insert-Client-Identifier-Step-3>";
   var signedClientId = knoxTokenLibraryJs.generateSignedClientIdentifierJWT("keys.json", clientId );
                   

   using knoxAPIUtility;
   var cert = "<insert path to keys.json>";
   var clientId = "<insert-Client-Identifier-Step-3>";
   var signedClientId = KnoxTokenUtility.generateSignedClientIdentifierJWT(cert, clientId );
                   

6. Generate your access token by calling the accesstoken REST API with your signed clientId and public key. The signed Client Identifier should be set as the value to clientIdentifierJwt in the request body of the accesstoken REST API. You can also set the token valid time between 1 — 30 minutes. The valid time is set to 30 minutes by default.

   For example:

   CURL

   curl -X POST <Knox-AccessToken-Endpoint> -H 'Content-Type: application/json' -d '{"clientIdentifierJwt": "signedClientId","base64EncodedStringPublicKey": "myPublicKey"}'

7. Sign your accesstoken with your private key, using the utility jar file as seen below.

   Java JavaScript .NET

   String accessToken = "myAccessToken";
   String signedAccessToken = KnoxTokenUtility.generateSignedAccessTokenJWT(new FileInputStream(cert), accessToken);
                   

   var accessToken  = "<insert-access-token>"
   var signedAccessToken = knoxTokenLibraryJs.generateSignedAccessTokenJWT("keys.json", accessToken );
                   

   var accessToken  = "<insert-access-token>"
   var signedAccessToken =KnoxTokenUtility.generateSignedAccessTokenJWT(cert, accessToken );
                   

   The signed accesstoken expires after its valid time runs out. Once that happens it returns the 403225 error code.

8. Enter your access token in the x-knox-apitoken header parameter of your Knox cloud service API request. See the API reference for your Knox cloud service for details.

   Here is an example of how to detect when the access token expires, get a fresh access token, and call a Knox Cloud Service API again.

   Java

   // Expired access token error code
   static String ACCESS_TOKEN_EXPIRED = "4032251";
   try {
       // Call Knox cloud service API
       callKnoxCloudService(signedAccessToken);
   } catch (Exception exception) {
       String responseBodyAsString = ((HttpClientErrorException) exception).getResponseBodyAsString();
       // Get error code value
       JsonNode code = new ObjectMapper().readTree(responseBodyAsString).get("code");
       // If error code matches expired access token error code, generate another token
       if (code.asText().equalsIgnoreCase(ACCESS_TOKEN_EXPIRED)) {
           // Generate a new access token by calling accesstoken API (Step 6)
           accessToken = getAccessToken(signedClientId, publicKey);
           // Sign your new access token (Step 7)
           signedAccessToken = KnoxTokenUtility.generateSignedAccessTokenJWT(new FileInputStream(<insert path to keys.json>), accessToken)
       }
   }