Authentication
Authenticate Genuka Pay API requests securely with your application secret key.
Introduction
Authenticated Genuka Pay calls use your application public_key plus an HMAC-SHA256 signature generated with your secret_key.
Credentials
Manage the current secret key and key rotation flow from the dashboard.
Request Security
Keep authentication strictly backend-side and never expose raw secrets.
Rotation
Rotate secrets when access changes, environments change, or exposure is suspected.
Required Headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATUREManage Credentials
Manage credentials from API Keys, not from a public API endpoint.
Open that page to reveal the current secret_key, review rotation history, or generate a new key when needed.
What the API Keys Page Usually Exposes
The API keys page commonly exposes:
idnameenvironment(SANDBOXorLIVE)statuspublic_keysecret_keybillablerotations
Signing a Request
import crypto from "crypto";
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = "POST";
const path = "/api/v1/payments"; // include the query string if there is one
const body = JSON.stringify({ amount: 1000, currency: "XAF", payer_phone: "+237677001122" });
const signature = crypto
.createHmac("sha256", process.env.GENUKA_SECRET_KEY!)
.update(timestamp + method + path + body)
.digest("hex");
await fetch(`${process.env.GENUKA_BASE_URL}${path}`, {
method,
headers: {
"X-Public-Key": process.env.GENUKA_PUBLIC_KEY!,
"X-Timestamp": timestamp,
"X-Signature": signature,
"Content-Type": "application/json",
},
body, // exactly the string you signed
});Send exactly the body you signed: re-serialising the object afterwards can change the bytes and break the signature. Every authentication failure returns 401 with {"message": "Unauthenticated."}.
Secret Rotation
If you need to rotate a compromised or aging key, go to API Keys.
Rotation replaces the secret_key immediately: the old one stops working at once, and the public_key does not change. Prepare the rollout of the new key before you click.
The recommended flow is:
- Reveal or generate the new
secret_key - Update backend environment variables or your secrets manager
- Restart affected services
- Verify payment, payout, and webhook flows
Operational rule
Treat secret rotation as a deployment event. Update the receiving backend, restart affected services, and verify webhook or payment flows immediately after rotation.
Example Authenticated API Call
Once you have retrieved the current secret_key from the dashboard, use it in backend API requests:
curl -X GET "https://api-pay.genuka.com/api/v1/payments" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE"Environment Discipline
Keep your authentication workflow strict:
- use separate credentials per environment
- never send live traffic with sandbox credentials
- never mix sandbox webhook receivers with live business flows
Recommendations
How is this guide?
Last updated on