Menu

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 an access token for your Knox MSP Program tenant

Complete these steps to generate your access token using the Knox Cloud Authentication API and successfully call the Knox cloud service APIs in the course of your MSP activities.

  1. Get access to Knox Cloud API
    1. Register for a Knox Partner Program account as a Managed Service Provider — ensure you select Knox Developer in the registration form
    2. Apply for Knox Cloud API access by contacting your local Samsung representative. If you can't get access through a Samsung Knox representative, please contact the Knox team through one of the following channels to request access.
      • Knox Partner Program dashboard: click Support and submit the web form
      • Knox Developers dashboard: click Support > Technical Support
  2. Generate your key pair on the Knox API Portal
    1. On the Knox Partner Portal, go to Knox Developers and click Knox Cloud API Portal.
    2. Click Download to download your public/private key pair JSON file. This JSON file only needs to be generated once contains the following information:
      • Public key — Key that is sent in the body of the accesstoken REST API request 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.
  3. Click GENERATE CLIENT IDENTIFIER under Knox MSP API. This unique identifier only needs to be generated once unless:
    • Privileges need to be changed.
    • The Client Identifier is lost or stolen.
    In both cases, re-generating the Client Identifier invalidates the previous one. Knox MSP Client identifier
  4. Get the support files.

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

    Download JAR
  5. Sign your Client Identifier with the token utility. See the source code below on how to sign your Client Identifier. For more information on using this utility jar, see the included README file in the .jar file download package.
    String clientId = "myClientId";
    String cert = "src/test/resources/keys.json";
    String signedClientId = KnoxTokenUtility.generateSignedClientIdentifierJWT(new FileInputStream(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 -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.
    String accessToken = "myAccessToken";
    String signedAccessToken = KnoxTokenUtility.generateSignedAccessTokenJWT(new FileInputStream(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 of your Knox cloud service for details. When you call a Knox cloud service API on behalf of your managed customers, you must include the x-wsm-managed-tenantid header parameter in your request, which identifies which customer you are managing with the API. Use your managed customer's ID as its value, which is found on the Customers page on the Knox MSP Portal.

    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.

    // 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)
        }
    }