API Key Authentication

Two ways to authenticate

Generating a key

Full API credentials are only ever generated inside the authenticated Merchant Portal — sign in at Merchant Portal, go to API Keys, choose Sandbox or Live, name the key, and check the scopes it needs (least privilege — a checkout integration only needs collections:write, for example). There is no public endpoint to generate a key — only POST /v1/merchant/api-keys, which requires a signed-in dashboard session:

{
  "name": "Production checkout server",
  "environment": "live",
  "scopes": ["collections:write", "payment_links:read"],
  "ip_whitelist_enabled": false,
  "continue_without_ip_whitelist": true
}

{
  "success": true,
  "data": {
    "id": "8f14e...",
    "name": "Production checkout server",
    "environment": "live",
    "key_prefix": "inf_live_9f2a1c3b",
    "key_last4": "d8e7",
    "scopes": ["collections:write", "payment_links:read"],
    "ip_whitelist_enabled": false,
    "continue_without_ip_whitelist": true,
    "plaintext_key": "inf_live_9f2a1c3bd8e7...",
    "status": "active",
    "created_at": "2026-08-14T09:00:00Z"
  }
}

Scopes

Every key is issued with an explicit set of scopes — it can only call the endpoints those scopes cover. A request with a key missing the required scope gets a 403, not a partial success.

Sandbox vs. Live

Every key is scoped to an environment. Sandbox keys (prefix inf_sandbox_...) run against a fully simulated provider — nothing settles for real, so you can build and test your entire integration risk-free. Live keys (inf_live_...) move real money. Sandbox keys never expire on their own; both can be revoked at any time.

Both are self-service — creating a Sandbox key never requires approval. A Live key is also created directly from the dashboard, the moment your business account is approved, KYC-verified, and has pricing assigned; there is no separate “request production access” step or waiting on Infinity Africa staff. Before that, creating a Live key returns:

{
  "success": false,
  "error": {
    "code": "production_access_restricted",
    "message": "Production API keys are available after your business account is approved."
  }
}

Using your key

Attach it as a header on every request — never as a query parameter or in the request body, where it's more likely to end up logged somewhere:

GET /v1/transactions/TXN-4821AB HTTP/1.1
Host: api.infinityafrica.net
Authorization: Bearer inf_live_9f2a1c3bd8e7...

IP whitelisting (optional)

Every key makes a choice, at creation, between two options — there is no default forced on you:

• Continue without IP whitelisting (the default) — the key authenticates from any server IP. Simpler, and fine for most integrations.
• Enable IP whitelisting — requests only succeed from IPs you explicitly approve. Add them from the Merchant Portal's IP Allowlist page (label, IP or CIDR, environment); each starts pending until a Super Admin approves it. A request from an unapproved IP gets a 403, and the attempt is logged.

Revoking or rotating a key

Rotate keys periodically from the Merchant Portal, revoke any key that may have leaked (committed to a public repo, shared in a support ticket, etc.) immediately rather than waiting for a scheduled rotation — and if you simply lose a key before copying it down, rotate is also how you recover: there is no way to view a key's secret again after creation, by design.