How do I authenticate to the Sunwave API using Postman?

Postman

If you are here for the Postman Collection/Environment you can download them here:

The environment and collection are setup with the authentication outlined below (once you’ve filled our the required environment variables). You don’t need to read about how the authentication works unless you are trying to implement it somewhere else.

API Authentication Scheme (Digest Seed + HMAC)

Sunwave’s API uses a custom Digest authorization header that is computed for every request. The Authorization value is not a static password. Instead, each request builds a short-lived signature that proves you know your API Secret and that the request has not been reused.

For every call, the client constructs a seed from:

The caller identity
An API key ID
A timestamp
The realm ID
A per-request transaction UUID
An MD5 fingerprint of the request payload

These values are concatenated in a strict order and signed using HMAC-SHA512 with your API Secret. The resulting signature is Base64-encoded using a URL-safe variant (replacing / with _ and + with -). The Sunwave server independently recomputes the same values to verify the request.

Authorization header format

Each request must include an Authorization header in the following format:

Authorization: Digest {{sunwave_email}}:{{API ID}}:{{dateTimebase64}}:{{realm_id}}:{{transactionId}}:{{base64md5Payload}}:{{hmac}}

What each field means

{{sunwave_email}} — User identity for the signing context (your email address).
{{API ID}} — Public identifier for the API key being used.
{{dateTimebase64}} — Base64-encoded UTF-8 timestamp. The timestamp format is:
Mon, 15 Jan 2026 13:45:12 -0700
{{realm_id}} — The realm context for the request.
{{transactionId}} — A UUID generated per request. This prevents replay attacks and helps with request tracing.
{{base64md5Payload}} — Base64-encoded UTF-8 MD5 hash of the raw request body, made URL-safe (/ → _, + → -). For GET requests or requests without a body, the raw body is treated as an empty string.
{{hmac}} — Base64-encoded HMAC-SHA512 signature of the seed, made URL-safe (/ → _, + → -).

The seed string that is signed is constructed exactly as:

seed = sunwave_email:API ID:dateTimebase64:realm_id:transactionId:base64md5Payload

Postman setup

Required environment variables

Create (or update) a Postman Environment with the following variables:

sunwave_email
API ID
API Secret
realm_id

These values are read by the pre-request script and used to compute the Authorization header.

Collection-level pre-request script

Add the following script at the Collection level so it runs automatically for every request. This script computes the values referenced by the Authorization header template.

In Postman: Collection → Edit → Pre-request Scripts, then paste the script below.

// Dependencies available in Postman’s sandbox
const moment = require('moment');
const uuid = require('uuid');

// 1) Timestamp formatted per scheme, then Base64-encoded
// Example timestamp: "Mon, 15 Jan 2026 13:45:12 -0700"
var dateTime = moment().format("ddd, D MMM YYYY HH:mm:ss ZZ");
var dateTimebase64 = CryptoJS.enc.Base64.stringify(
  CryptoJS.enc.Utf8.parse(dateTime)
);

// 2) Read required environment variables
var sunwave_email = pm.environment.get("sunwave_email");
var apiId = pm.environment.get("API ID");
var apiSecret = pm.environment.get("API Secret");
var realm_id = pm.environment.get("realm_id");

// 3) Per-request unique transaction id
var transactionId = uuid.v4();

// 4) Get the raw request body (or empty string for GET/no-body requests)
var rawBody = (pm.request.body && pm.request.body.raw) ? pm.request.body.raw : "";

// 5) MD5 of raw body, then Base64 encode, then make URL-safe
// Note: md5Payload is a hex string; the scheme Base64-encodes the UTF-8 bytes of that hex string.
var md5Payload = CryptoJS.MD5(rawBody).toString();

var base64md5Payload = CryptoJS.enc.Base64.stringify(
  CryptoJS.enc.Utf8.parse(md5Payload)
).replaceAll('/','_').replaceAll('+', '-');

// 6) Construct the seed string in the required order
var seed =
  sunwave_email + ":" +
  apiId + ":" +
  dateTimebase64 + ":" +
  realm_id + ":" +
  transactionId + ":" +
  base64md5Payload;

// 7) HMAC-SHA512(seed, API Secret), Base64 encode, then URL-safe replace
var hmacBase64 = CryptoJS.enc.Base64.stringify(
  CryptoJS.HmacSHA512(
    CryptoJS.enc.Utf8.parse(seed),
    CryptoJS.enc.Utf8.parse(apiSecret)
  )
).replaceAll('/','_').replaceAll('+', '-');

// 8) Publish computed values so the Authorization header template resolves
pm.environment.set("dateTimebase64", dateTimebase64);
pm.environment.set("transactionId", transactionId);
pm.environment.set("hmac", hmacBase64);
pm.environment.set("base64md5Payload", base64md5Payload);

Request Authorization settings in Postman

Set the Authorization type to No Auth for each request, or set it once at the collection or folder level. This ensures Postman does not override your custom Authorization header with one of its built-in auth helpers.

Notes and common issues

The Authorization header is generated fresh for every request. Reusing a previous header will fail.
Any change to the request body changes the MD5 payload fingerprint and therefore the signature.
For GET or no-body requests, the script always hashes an empty string.
If you receive authentication errors, confirm the environment variables, realm ID, and that Authorization is set to No Auth.