Menu

Generate a Knox Cloud Services signed access token

Retrieving and signing a Knox Cloud Services (KCS) access token forms the second stage of third party integration with KCS. 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 KCS access token

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

Example accesstoken request body:

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

NOTE — When your KCS access token expires, you can use the accesstoken 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 KCS access token >" 
}

3. Sign your KCS 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 KCS access token >);

4. Start making KCS API calls

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

Include your signed KCS 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.

NOTE — 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 KCS 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: