Authentication

Every request to a Dynamo API is signed. There are no cookies or bearer tokens — you authenticate by computing an HMAC-SHA256 signature over the request timestamp with your organization's secret.

You need two credentials, both issued per organization:

• API key — a public identifier (a document id), sent as x-api-key.
• Secret — used only to sign requests; never sent over the wire.

The headers

The signature is computed over the x-date string only — not the body, path, or any other header. x-api-version is not part of the signature.

Generate the signature

1. Format the timestamp. Take the current request time (milliseconds) and format it as an IMF-fixdate string in GMT, US locale: EEE, dd MMM yyyy HH:mm:ss z (e.g. Sun, 06 Dec 2020 12:59:11 GMT). In JavaScript this is exactly new Date().toUTCString(). Use this string as the x-date header value.
2. Sign it. Compute HMAC-SHA256 over the x-date value, keyed by your organization secret, and encode the result as a hexadecimal string. Use this as the x-signature header value.
3. Send x-api-key, x-date, x-signature, and x-api-version on the request.

Signing a request

const crypto = require("crypto");

function authHeaders(apiKey, secret) {
  const xDate = new Date().toUTCString(); // e.g. Sun, 06 Dec 2020 12:59:11 GMT
  const signature = crypto
    .createHmac("sha256", secret)
    .update(xDate)
    .digest("hex");
  return {
    "x-api-key": apiKey,
    "x-date": xDate,
    "x-signature": signature,
    "x-api-version": "1", // External API only; ignored by the Audience API
  };
}

XDATE=$(LC_ALL=C TZ=GMT date "+%a, %d %b %Y %H:%M:%S GMT") # IMF-fixdate

SIG=$(printf '%s' "$XDATE" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -H "x-api-key: $KEY" \
     -H "x-date: $XDATE" \
     -H "x-signature: $SIG" \
     -H "x-api-version: 1" \
     "$BASE/channels"

The same helper works for both APIs — just point it at the right base URL:

Example

Check your implementation against this known pair — the same x-date and secret must produce the same signature:

const date = 'Mon, 14 Feb 2022 20:35:03 GMT'; // new Date().toUTCString()
const secret = 'xZcLnmVhtl7MAlEgMnYI';

const signature = CryptoJS.HmacSHA256(date, secret).toString(CryptoJS.enc.Hex);
// bf4a8eea118be91013805e443cc4218e8410df136ed4276da5efb5dcab6812f7

Auth error responses

API version

Send x-api-version: 1 on every External API request — it's required, and a missing or unknown value returns 400. Pinning a version means our deploys won't break you: today the only value is 1, and any future breaking change ships as a new version (announced here, with Deprecation / Sunset / Link response headers giving a migration window before an old version is retired). The /v1 in the base URL is the stable API generation; x-api-version is the revision within it. The Audience API doesn't require the header — it's accepted and ignored there.

Next steps