Menu

NOTE - If you're a third party portal provider wanting to make calls to KCS on behalf of your customers, see Third party integration.

Tutorial: Generate access token

These are the steps you must complete to generate your access token using the Knox Cloud Authentication API and successfully call the Knox Cloud Services APIs.

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

Step 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 by clicking Download*. This file is saved to your browser's default download folder. 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 API is supported by the following browsers: Chrome, Firefox, Safari, Internet Explorer 10 or 11. In order to get the best possible Knox API experience, upgrade your preferred browser to the latest version.

Step 3: Generate your unique Client Identifier from the Knox API Portal

Obtain your 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. This image below shows the page you see when generating the Client Identifier from the portal.

Knox Cloud Portal

Step 4: Download the support files

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

Download JAR

Step 5: Sign your Client Identifier with the .jar file

Sign your Client Identifier with the jar file supplied above. The signed Client Identifier is now referred to as the clientIdentifierJwt in the body of the accesstoken REST API. 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.

    String clientId = "myClientId";
    String downloadedCertificate = "src/test/resources/certificate.json";
    String clientIdentifierJwt = KnoxTokenUtility.generateSignedClientIdentifierJWT(new FileInputStream(downloadedCertificate), clientId);

Note: The clientIdentifierJwt frequently expires after it is signed using the utility jar. Once this happens it returns the 4032251 error code.

Step 6: Generate your access token

Generate your access token by calling the accesstoken REST API. Pass in the clientIdentifierJ and public key you created earlier.

For example:

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

Step 7: Sign your access token with private key

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

    String apiToken = "myApiToken";

    String signedApiAccessToken = KnoxTokenUtility.generateSignedAccessTokenJWT(new FileInputStream(downloadedKeyPair), apiToken);

Note: The clientIdentifierJwt frequently expires after it is signed using the utility jar. Once this happens it returns the 403225 error code.

Step 8: Call the Knox Cloud Service API

Now that you have successfully generated your access token, you can call a Knox Cloud Service API.

For example:

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

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.

    // code for expired access token
    static String ACCESS_TOKEN_EXPIRED = "4032251";


    // call Knox api to retrieve access token
    String accessToken = getAccessToken();


    // sign the access token using private key

    String signedAccessToken = signAccessToken(downloadedKeyPair, accessToken);


    // call KnoxCloudService api

    try {
        callKnoxCloudService(signedAccessToken);
    } catch (Exception exception) {

        String responseBodyAsString = ((HttpClientErrorException) exception).getResponseBodyAsString();

        // check value of code
        JsonNode code = new ObjectMapper().readTree(responseBodyAsString).get("code");

        // if code matches the expired access token, call the api again for a fresh access token
        if (code.asText().equalsIgnoreCase(ACCESS_TOKEN_EXPIRED)) {
            callKnoxApi();
        }
      }
    }