Allowlist

The allowlist makes recipients eligible for utility messages without Akedly ever seeing your contact list. Numbers are hashed on your device — in your browser or on your own server — and only the hashes are uploaded. Your plaintext numbers never leave your device.

How the allowlist works

Each pipeline stores a set of HMAC digests. At send time, Akedly canonicalizes the recipient's number, computes the same HMAC with the pipeline's hash secret, and checks membership — a match is the allowlist eligibility proof.

Because the server keeps the secret, a leaked database of hashes cannot be reversed or brute-forced into phone numbers, and hashes from one pipeline never match another pipeline's list.

Enable the allowlist proof in the pipeline's Audience settings; upload and manage the list from the Allowlist panel or the API below.

Upload from the dashboard

The primary path is your pipeline's Allowlist panel: paste your numbers and they are hashed in your browser, on your device, before anything is sent. Your numbers never leave your device — what is uploaded is the list of 64-hex digests, never a phone number.

Paste from anywhere — one number per line, commas also split (paste-only by design; there is no file upload). The panel canonicalizes, deduplicates, hashes with your pipeline's hash secret, uploads the digests, and shows the added / skipped / invalid outcome.

For very large lists, automation, or high-assurance workflows, use the downloadable script — the same device-local hashing, run from your terminal.

Hashing rules

A hash is HMAC-SHA256(canonicalE164, hashSecret), hex-encoded — 64 hex characters per number.

const crypto = require("crypto");

const hmac = crypto
  .createHmac("sha256", process.env.AKEDLY_HASH_SECRET)
  .update("+201234567890") // canonical E.164
  .digest("hex");

Pin your implementation against this test vector before uploading — a drifted hash uploads fine but never matches at send time:

HMAC-SHA256(key="uhs_selftest", message="+201234567890")
= c638f9bf33b95e279de31800542a12517cec60b889c6d1caf4223846a07afe60

Upload with the script

The easiest path: your pipeline's Allowlist panel offers a ready-made script — hash-allowlist.js (Node.js), hash_allowlist.py (Python), or hash_allowlist.php (PHP) — downloaded with your pipeline ID pre-filled. Each canonicalizes, deduplicates, hashes, self-tests against the vector above, and refuses to run if its canonicalization drifts from Akedly's. The Node.js script is the full tool — it adds --check verification, the hash-key preflight, and batch splitting; the Python and PHP ports cover hashing and upload.

# 1. Dry run — parse, canonicalize, hash; print the hashes, upload nothing
node hash-allowlist.js numbers.csv

# 2. Upload — preflights your hash key, then uploads in batches
node hash-allowlist.js numbers.csv --upload

# 3. Verify — ask Akedly if a number is now eligible
node hash-allowlist.js --check +201001112222

The input file is plain text (.csv or .txt) — one number per line; commas and semicolons also split; blank lines are ignored.

The scripts call the API endpoints below, so they need a verified account: without the entitlement, --upload (including its key-fingerprint preflight) and --check both return 403 FEATURE_NOT_ENABLED. Hashing a file without --upload is entirely local and works regardless.

Configure the script through environment variables:

Before uploading, the Node.js script compares a fingerprint of your local hash secret against the pipeline's current one and hard-stops on mismatch — catching the silent failure where hashes computed with a stale secret upload successfully but never match. With the Python or PHP port, run the preflight yourself via the key-fingerprint endpoint.

Ingest hashes

const crypto = require("crypto");

async function uploadAllowlist(hmacs) {
  const body = JSON.stringify({
    APIKey: process.env.AKEDLY_API_KEY,
    pipelineID: process.env.AKEDLY_PIPELINE_ID,
    hmacs, // 64-hex digests, hashed on your machine
  });

  // sign the exact body bytes with the pipeline's SIGNING secret (usk_), not the hash secret
  const timestamp = Date.now().toString();
  const nonce = crypto.randomBytes(16).toString("hex");
  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
  const signature = crypto
    .createHmac("sha256", process.env.AKEDLY_SIGNING_SECRET)
    .update(`${timestamp}.${nonce}.${bodyHash}`)
    .digest("hex");

  const res = await fetch("https://api.akedly.io/api/v1/utilities/allowlist", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-akedly-timestamp": timestamp,
      "x-akedly-nonce": nonce,
      "x-akedly-signature": signature,
    },
    body,
  });
  return res.json();
}

{
  "APIKey": "<AKEDLY_API_KEY>",
  "pipelineID": "<YOUR_PIPELINE_ID>",
  "hmacs": [
    "c638f9bf33b95e279de31800542a12517cec60b889c6d1caf4223846a07afe60",
    "a3f8c92e6b41d7f05c1e8b26d94a7310f6e21d94c87bb52e0d3c5a19b48e7f02",
    "7bd410c25e98aa130f6e21d94c87bb52a3f8c92e6b41d7f05c1e8b26d94a7310"
  ],
  "countries": { "EG": 2, "SA": 1 },
  "note": "Q3 loyalty cohort"
}

{
  "status": "success",
  "message": "Allowlist updated",
  "data": {
    "added": 4980,
    "skipped": 15,
    "invalid": 5,
    "total": 12480
  }
}

Check eligibility

{
  "APIKey": "<AKEDLY_API_KEY>",
  "pipelineID": "<YOUR_PIPELINE_ID>",
  "phone": "+201001112222"
}

{
  "status": "success",
  "data": {
    "eligible": true,
    "proof": "allowlist"
  }
}

Verify your hash key

{
  "APIKey": "<AKEDLY_API_KEY>",
  "pipelineID": "<YOUR_PIPELINE_ID>"
}

{
  "status": "success",
  "data": {
    "fingerprint": "3b7f0a2c"
  }
}

Limits and errors

Allowlist endpoints share a burst guard: 100 requests per minute per pipeline. A 429 includes a Retry-After header and cooldownSeconds.

Authentication and pipeline errors (INVALID_API_KEY, PIPELINE_NOT_FOUND, NOT_A_UTILITY_PIPELINE, …) match the send error reference. Allowlist-specific errors:

Rotating the hash secret

Regenerating the hash secret clears the pipeline's allowlist — entries hashed with the old secret can never match again, so Akedly removes them rather than leave dead rows.

Next: send to them

Once numbers are eligible, deliver with the Send API, or attach your own user IDs to eligible numbers with End Users.