Authentication
Every partner request is authenticated twice, deliberately: an HMAC signature proves the request came from someone holding your secret and wasn't altered in transit, and a bearer token proves an active, scoped session. The two are checked together, a valid signature from client A paired with a token belonging to client B is rejected, not quietly accepted.
topuprelay-sdk signs every request and manages the token lifecycle for you, nothing below is something a Node integration needs to implement by hand.1. Sign the request
Three headers carry the signature:
| Header | Value |
|---|---|
| X-Client-Key | Your public client key (e.g. ck_test_...) |
| X-Timestamp | Current Unix time in seconds |
| X-Signature | Hex HMAC-SHA256, computed as described below |
The string to sign is five fields joined with |:
{client_key}|{timestamp}|{METHOD}|{path}|{sha256_hex(raw_request_body)}
Example, for POST /api/v1/partner/vtu/airtime with body {"network":"mtn","phone":"08011112222","amount":"200.00"}:
ck_test_abc123|1732000000|POST|/api/v1/partner/vtu/airtime|9f1c2... (sha256 of the exact JSON bytes sent)- • Method is upper-case (GET, POST, …).
- • Path is the request path only, no query string, leading slash included.
- • Body hash is a plain SHA-256 of the exact bytes you send, for a GET request with no body, this is the hash of an empty string.
- • The final signature is
HMAC-SHA256(signing_string, api_secret), hex-encoded.
import crypto from "node:crypto";
function signRequest(clientKey, apiSecret, method, path, bodyString) {
const timestamp = Math.floor(Date.now() / 1000).toString();
const bodyHash = crypto.createHash("sha256").update(bodyString).digest("hex");
const signingString = [clientKey, timestamp, method.toUpperCase(), path, bodyHash].join("|");
const signature = crypto.createHmac("sha256", apiSecret).update(signingString).digest("hex");
return {
"X-Client-Key": clientKey,
"X-Timestamp": timestamp,
"X-Signature": signature,
};
}2. Exchange it for a token
POST /partner/auth/token and POST /partner/auth/token/refresh are the only two endpoints that accept a signature alone, every other endpoint also requires the bearer token this returns. That's deliberate: gating refresh behind a token would make an already-expired token impossible to refresh.
{
"success": true,
"data": {
"tokens": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3599
}
}
}- • Access tokens last 60 minutes.
- • Refresh tokens last 14 days from original issuance, refreshing extends the access token, not the 14-day window itself.
- • Send the access token as
Authorization: Bearer <token>on every other request, alongside the same three signature headers.
3. Replay protection
A timestamp more than 5 minutes old or in the future is rejected outright. Within that window, the exact same signed request, same client, timestamp, method, URL, and body, can only be processed once; a repeat is rejected with REPLAY_DETECTED. Generate a fresh timestamp (and therefore a fresh signature) for every request, don't cache and reuse one.