Identifier hashing

Asqary recognises the same customer, device or beneficiary across transactions by hash. Every integration must compute hashes identically: the SDKs, the dashboard’s in-browser CSV hashing, and any code you write yourself.

The API rejects anything that is not a 64-character hex hash.

The algorithm

hash = lowercase hex( HMAC-SHA256( key = identifier key bytes,
                                   message = UTF-8(identifier with surrounding whitespace removed) ) )

The fields that take a hash are customer.id_hash, customer.bvn_hash, customer.phone_hash, device.id_hash and beneficiary.account_hash.

Your identifier key

You generate it once and keep it in a secrets manager:

openssl rand -hex 32

Asqary never receives it and cannot reverse the hashes.

Rule	Requirement
Length	32–64 bytes of random key material
Encoding	Hex (64–128 characters, even length), or base64 / base64url (padding optional) decoding to 32–64 bytes. A key made only of hex characters is read as hex.
Size limit	At most 128 characters
Characters	No whitespace (a trailing newline from a .env file is rejected), nothing outside the hex or base64 alphabets
Randomness	At least 10 distinct characters

Caution

Use the same key everywhere: every service that calls Asqary, and the dashboard when you upload a backtest CSV. Otherwise the same customer looks like different people.

Do not change it. A new key gives every customer new hashes, so their behavioural history starts over.

Normalise before hashing

Only surrounding whitespace is removed for you. Normalise everything else so one customer always hashes the same way, for example phone numbers in E.164 (+2348012345678).

Examples

Node.js

import { createHmac } from "node:crypto";

const key = Buffer.from(process.env.ASQARY_IDENTIFIER_KEY!, "hex");
const hash = (value: string) => createHmac("sha256", key).update(value.trim(), "utf8").digest("hex");

hash("customer_456");

Python

import hashlib, hmac, os

key = bytes.fromhex(os.environ["ASQARY_IDENTIFIER_KEY"])

def asqary_hash(value: str) -> str:
    return hmac.new(key, value.strip().encode("utf-8"), hashlib.sha256).hexdigest()

Shell

printf '%s' "customer_456" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$ASQARY_IDENTIFIER_KEY" -hex

Test vectors

Check your implementation against these. The key is for testing only and is rejected as a real key.

Key (hex): 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f The same bytes in base64: AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=

Identifier	Hash
customer_456	5383ffaa5a59ca0a5a99c4b802975214c447f489fee616aaf5672ca5a4ba9210
22345678901	755f4e5caac39ecff329b10b819894c7161889f3bba020b2d5799e5b7f02cf0c
" 0123456789 " (trimmed first)	cd286ad0f9a6fd4f78afcd163bc33b55ed507590044bd1961428c16dd3eed449
+2348012345678	3f791c02fe92009ed436e0c5d4d3f00af33bbd99b8cb52757800321bf65f06a9