Widget Identity

Widget Access Key and Secret Key

Upon creation of your widget, an accessKey and a secretKey are automatically assigned to you. These keys are provided for secure communication when your backend interacts with portal services.

Currently, the primary use of these keys is for secure calls to order management APIs. In the future, their use might be expanded to other service interactions.

• accessKey: This acts as your widget's unique identifier. When creating a JWT for secure communication, your accessKey must be used as the value for the iss (issuer) claim within the JWT payload.

• secretKey: This is a confidential key used to sign the JWT. This signature ensures the token's authenticity and integrity. Keep this key confidential.

In short, accessKey identifies you (as the issuer in the JWT), and secretKey is used to sign the JWT, proving the request is authentic and secure, currently for order management tasks.

Here is a Node.js example demonstrating how to generate a JWT with the required payload structure (iss, exp, nbf) and sign it using your secretKey, conforming to the JWT standard:

Generating JWT for Secure Communication (Node.js)

This snippet uses the jsonwebtoken library to create a JWT with your accessKey as the iss claim and signed with your secretKey.

JavaScript

const jwt = require('jsonwebtoken');

// --- Your Assigned Keys ---
const widgetAccessKey = 'wgt_ak_ae8e70cd2d7ee69c9e739562e'; // Your assigned access key
const widgetSecretKey = 'YOUR_ASSIGNED_SECRET_KEY'; // Your assigned secret key - Keep this secret!

// --- Define JWT Payload (Claims) ---
// The payload must include required standard claims.
// 'iss' must be your accessKey.
// 'exp' and 'nbf' define the token's validity period.
// Timestamps are in seconds (Unix time).
const currentTimeInSeconds = Math.floor(Date.now() / 1000);

const jwtPayload = {
  iss: widgetAccessKey,               // Issuer: Set to your widget's accessKey
  iat: currentTimeInSeconds,          // Issued At: Current timestamp
  exp: currentTimeInSeconds + (60 * 5), // Expiration Time: e.g., 5 minutes from now
  nbf: currentTimeInSeconds - (60 * 1), // Not Before: e.g., 1 minute ago (allows for clock skew)
  // You can add other custom claims here if needed by the API
  // userId: 'user123',
  // orderId: 'ORDER456'
};

// --- Generate and Sign the JWT ---
// jwt.sign creates the Header, Payload, and Signature.
// It uses the payload object, your secret key, and the signing algorithm (default is HS256).
const token = jwt.sign(jwtPayload, widgetSecretKey); // HS256 is the default algorithm if not specified

console.log("Payload used for JWT:", jwtPayload);
console.log("Generated JWT for secure communication:");
console.log(token);

// --- How to use the JWT ---
// You would typically include this generated 'token' in an HTTP header (e.g., 'Authorization: Bearer <token>')
// or within the request body when calling order management APIs that require this authentication.

// --- Verification (Recipient Side - Conceptual) ---
// The recipient (e.g., portal API) would receive the token, extract the payload,
// get the 'iss' (accessKey), look up the corresponding secretKey, and verify the signature
// and validate the claims (exp, nbf, etc.).
/*
jwt.verify(token, widgetSecretKey, (err, decodedPayload) => {
  if (err) {
    console.error('JWT verification failed:', err.message);
  } else {
    console.log('JWT is valid. Decoded Payload:', decodedPayload);
    // Check decodedPayload.iss matches the expected issuer
    // Check other claims as needed
  }
});
*/

Explanation:

1. We require the jsonwebtoken library.

2. We define your accessKey (widgetAccessKey) and secretKey (widgetSecretKey).

3. We create the jwtPayload object. This object includes the mandatory iss, iat, exp, and nbf claims with appropriate values. The iss claim is set to your accessKey.

4. jwt.sign(jwtPayload, widgetSecretKey) generates the JWT string. By default, jsonwebtoken uses HS256 with a secret key, which is a common standard.

5. The generated token is the JWT string you will include in your API calls to the portal for authentication.

Remember to replace the placeholder values for widgetAccessKey and widgetSecretKey with your actual assigned keys. Ensure your server's clock is reasonably synchronized for exp and nbf claims to work correctly.