Back to top

Generate a Knox cloud services signed access token

Last updated April 30th, 2024

Retrieving and signing a Knox cloud services access token forms the second stage of third party integration with Knox cloud services. Ensure you have a valid Samsung Account access token before proceeding. For more information on retrieving a Samsung Account access token, see Authorize a user with Samsung Account.

1. Sign your Client Identifier with your Samsung Account access token

Sign your Knox Client Identifier with the Knox token utility using your Samsung Account access token. For more information on downloading and using the Knox token utility, see Knox API token library.

You can get your public key using KnoxTokenUtility.generateBase64EncodedStringPublicKey() as shown:

// Downloaded from the Knox Portal 
String clientIdentifier = <Your Client Identifier>; 
String downloadedKeys = <insert path to keys.json>; 

// Retrieved using the Samsung Account token API  
String saAccessToken = < Your Samsung Account access token >; 


String publicKey = KnoxTokenUtility.generateBase64EncodedStringPublicKey(
    new FileInputStream(new File(downloadedKeys))); 
String signedClientIDJWT = KnoxTokenUtility.generateSignedclientIdentifierJwtWithIdpAccessToken(
    new FileInputStream(new File(downloadedKeys)),
    clientIdentifier,
    saAccessToken);

2. Get a Knox cloud services access token

Generate your access token by passing your signed Samsung Account access token and public key to the accessTokenOAuth2 endpoint. Optionally set the token’s validity by including a value for validityForAccessTokenInMinutes in the request body.

Example accessTokenOAuth2 request body:

{ 
    "base64EncodedStringPublicKey": "<your-public-key>",
    "clientIdentifierJwt": "<your-signed-clientIdentifierJwt>",
    "validityForAccessTokenInMinutes": 30
}

When your Knox cloud services access token expires, you can use the accessTokenOAuth2 endpoint to repeatedly request a new access token until the session token is invalidated or expires. You must sign the Samsung Account access token before each of these requests to avoid replay attacks.

Example response:

{ 
    "accessToken": "<Your unsigned Knox cloud services access token >"
}

3. Sign your Knox cloud services access token

Sign your access token with your private key using the Knox token utility. The access token will be valid for 30 minutes once signed. You can use the refresh token (see step 5) to get a new token after it expires.

String signedAccessToken = KnoxTokenUtility.generateSignedAccessTokenJWT(
                                new FileInputStream(new File(downloadedKeys)), 
                                < Your unsigned Knox cloud services access token >);

4. Start making Knox cloud services API calls

This completes the third-party integration tutorial. You can now start making calls to Knox cloud services APIs to access end customer data with your signed Knox cloud services access token.

Include your signed Knox cloud services access token as a header parameter when requesting resources on behalf of your customer. Check out step 5 of the KME tutorial to see an example of using the KME API to assign device profiles.

You can also browse the detailed KME API reference, which includes example calls.

If this step fails, ensure that your end customers have established a full trust relationship with your portal.

5. Regenerate access token using refresh token

You can regenerate the Knox cloud services access token when it expires using the Refresh Token. The Refresh Token can be found in the response of Samsung Account access token.

See also:

Is this page helpful?