Authentication

API keys, JWT sessions, and when to use each.

Method	Header	Use when
API key	Authorization: ApiKey nz_test_...	Server automation, CI, backends
JWT	Authorization: Bearer <access_token>	User login, dashboard apps
Public	(none)	Checkout confirm, payment links, MNO status

API keys

Create keys in Dashboard → Settings → API keys. Test keys use the nz_test_ prefix; live keys use nz_live_. The full key is shown once at creation.

client = NezaHubClient(api_key="nz_test_abc123")

Login (JWT)

bootstrap = NezaHubClient()
session = bootstrap.auth.login(phone="+254712345678", password="your-password")
client = NezaHubClient(access_token=session["tokens"]["access"])

me = client.auth.me()

Two-factor authentication

Payouts and wallet transfers require 2FA. The first request returns HTTP 403 with challenge_id. Verify the OTP with verify_2fa(), then retry with the same challenge_id.

Python

try:
    client.payouts.create(..., challenge_id="pending")
except NezaHubError as e:
    challenge_id = e.payload["challenge_id"]

client.auth.verify_2fa(challenge_id=challenge_id, code="123456")
client.payouts.create(..., challenge_id=challenge_id)