Using Postman

This guide will help you import the ONLIVE.SITE OpenAPI collection into Postman and configure automatic authentication for all endpoints.

Step 1: Import the OpenAPI Collection

1. Download the OpenAPI JSON file

   • Access the ONLIVE.SITE API documentation
   • Download the json-api.json file.

2. Import into Postman

   • Open Postman
   • Click the "Import" button in the upper left corner
   • Drag and drop the JSON file or select it using the "Choose Files" button
   • Postman will automatically detect that it's an OpenAPI file
   • Click "Import" to confirm

3. Verify the import

   • The collection will appear in your left sidebar with all endpoints organized
   • Explore the folders to see all available endpoints

Step 2: Configure Collection Variables

Before setting up authentication, you need to add your credentials:

1. Right-click on the imported collection and select "Edit"
2. Go to the "Variables" tab
3. Add the following variables:

Variable	Type	Initial Value	Current Value
accessKeyId	default	your-access-key-id	your-access-key-id
secretKeyId	secret	your-secret-key	your-secret-key

tip

Mark secretKeyId as "secret" type so Postman will hide the value in the interface.

4. Click "Save" to save the changes

Step 3: Configure the Pre-request Script

The pre-request script will run automatically before each request to calculate and add the authentication signature.

1. Open the collection settings

   • Right-click on the collection
   • Select "Edit"

2. Go to the "Pre-request Script" tab

3. Copy and paste the following script:

// Postman Pre-request Script for Onlive.site OpenAPI

// 1. Get your credentials from Postman collection variables
const accessKeyId = pm.collectionVariables.get("accessKeyId");
const secretKey = pm.collectionVariables.get("secretKeyId");

if (!accessKeyId || !secretKey) {
    console.error("Please define 'accessKeyId' and 'secretKeyId' in your Postman collection variables.");
    return;
}

// 2. Generate the Timestamp in YYYYMMDDTHHmmssZ format
function pad(number) {
    return ("00" + number).slice(-2);
}
const now = new Date();
const timestamp = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}T${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}Z`;

// Add the date header to the request. Postman will replace it if it already exists.
pm.request.headers.upsert({
    key: 'x-onlive-site-date',
    value: timestamp
});

// 3. Create the "String to Sign"
const method = pm.request.method.toUpperCase();
const path = pm.request.url.getPath();
const queryParams = pm.request.url.query;
const body = pm.request.body ? pm.request.body.toString() : "";


// 3.1. Create the Canonical Headers
// Filter headers that start with 'x-onlive-site-', convert them to lowercase, and sort them.
const onliveHeaders = [];
pm.request.headers.all().forEach(header => {
    const keyLower = header.key.toLowerCase();
    if (keyLower.startsWith('x-onlive-site-')) {
        onliveHeaders.push({
            name: keyLower,
            value: header.value.trim()
        });
    }
});
onliveHeaders.sort((a, b) => a.name.localeCompare(b.name));
const canonicalHeaders = onliveHeaders.map(h => `${h.name}:${h.value}`).join('\n');


// 3.2. Create the Canonical Query String
// Sort the URL parameters alphabetically.
const sortedQueryParams = [];
queryParams.each(param => {
    // Ignore disabled parameters
    if (param.disabled) return;
    sortedQueryParams.push({
        name: encodeURIComponent(param.key),
        value: encodeURIComponent(param.value)
    });
});
sortedQueryParams.sort((a, b) => a.name.localeCompare(b.name));
const canonicalQueryString = sortedQueryParams.map(p => `${p.name}=${p.value}`).join('&');


// 3.3. Create the Hashed Payload
// Hash the request body with SHA-256.
const hashedPayload = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);

// 3.4. Assemble the final "String to Sign"
const stringToSign = `${method}\n${canonicalHeaders}\n${path}\n${canonicalQueryString}\n${hashedPayload}`;

// For debugging, you can uncomment the following line to see the string to be signed
// console.log("String to Sign:", stringToSign);

// 4. Calculate the Signature
// Use HMAC-SHA256 with your Secret Key.
const signature = CryptoJS.HmacSHA256(stringToSign, secretKey).toString(CryptoJS.enc.Hex);


// 5. Add the Authorization Header
const authorizationHeader = `ONLIVESITE Credential=${accessKeyId}, Signature=${signature}`;

// Add the authorization header to the request.
pm.request.headers.upsert({
    key: 'Authorization',
    value: authorizationHeader
});

4. Click "Save" to save the script

Step 4: Test the Configuration

1. Select any endpoint from the collection
2. Click "Send"
3. Verify the response
   • If the configuration is correct, you will receive a successful response (200, 201, etc.)
   • If there's an authentication error (401), verify that your credentials are correct

Debugging

If you encounter authentication issues:

1. Open the Postman Console

   • Go to View > Show Postman Console
   • Or use the shortcut Cmd+Alt+C (Mac) / Ctrl+Alt+C (Windows)

2. Uncomment the debug line in the script

   console.log("String to Sign:", stringToSign);

3. Send the request again and check the console to see the string being signed

4. Verify that your credentials are correct

   • Access Key ID should be without additional spaces
   • Secret Key should be without additional spaces

How the Script Works

The script automatically performs the following steps:

1. Retrieves credentials from collection variables
2. Generates a timestamp in UTC format (YYYYMMDDTHHmmssZ)
3. Adds the header x-onlive-site-date with the timestamp
4. Creates a canonical string that includes:
   • HTTP method
   • Headers starting with x-onlive-site- (alphabetically sorted)
   • Endpoint path
   • Query parameters (alphabetically sorted)
   • SHA-256 hash of the body
5. Calculates the signature using HMAC-SHA256 with your Secret Key
6. Adds the authorization header with the format: ONLIVESITE Credential={accessKeyId}, Signature={signature}

info

The script runs automatically before each request in the collection, so you don't need to worry about manual authentication.

Important Notes

• ✅ The timestamp must be within 15 minutes of server time
• ✅ Make sure you have an internet connection to synchronize the time correctly
• ✅ Credentials are stored securely in collection variables
• ✅ The script uses the CryptoJS library that comes included with Postman

Next Steps

Once authentication is configured, you can:

• Explore all available endpoints in the collection
• Create and save request examples
• Organize requests into custom folders
• Export the collection with your settings to share with your team

For more information about authentication, see the authentication documentation.