Authentication

Every request to /v1 is authenticated with an API key. Merchant identity is derived entirely from the key — there is no tenant header and no version header (versioning is path-based via /v1).

Key formats

Keys encode their type and environment:

pk_test_…   publishable, test
pk_live_…   publishable, live
sk_test_…   secret, test
sk_live_…   secret, live

Secret keys (sk_) are server-to-server and are required for writes.
Publishable keys (pk_) are for browsers and other untrusted clients.
Using a pk_ where a secret is required returns 403 Secret key required.

Keys are stored hashed (SHA-256). The full key is shown only once, when it is created. Bizzle exposes a short keyPrefix for identification.

The auth header

Send your key as a bearer token:

Authorization: Bearer sk_live_…

Alternatively:

X-API-Key: sk_live_…

A missing credential returns 401.

Test mode

The environment is carried in the key itself. Test keys route to a deterministic sandbox provider; live keys hit the real rails (ClickPesa and mobile-money networks).

Test records are tagged with test-mode metadata and skipped by background jobs, so sandbox data can never reach the live pipeline. Events carry livemode: false.

Request logs

Every /v1 response includes an X-Request-Id. GET /v1/logs returns recent requests made with your keys, which is the fastest way to debug an integration.