Authentication

Authorization: Bearer sk_test_...

Create keys on the API Keys page of your dashboard. sk_test_ keys simulate M-Pesa and never move wallet balances. sk_live_ keys move real money. Never put a live key in a browser or mobile app.

The key is shown once. SwiftWallet stores only a hash, so a lost key cannot be recovered; revoke it and create a new one.

Checks, in order

API_KEY_NOT_IN_HEADER (401): a key was sent in the query string or body.
INVALID_API_KEY (401): missing, unknown, inactive or revoked key.
API_KEY_EXPIRED (401).
USER_INACTIVE (403): the account is suspended.
ACCOUNT_NOT_VERIFIED (403): verify your email first.
IP_NOT_ALLOWED (403): the key's IP allowlist does not include the caller.
RATE_LIMIT_EXCEEDED (429). The request counts against your limit from this point on.
SERVICE_NOT_PERMITTED (403): the key lacks the route's scope. details.required_scope names it.

Scopes

Scope	Endpoints
`stk_push`	`POST /v3/stk-initiate` `POST /v3/lipa-na-mpesa`
`b2c_payments`	`POST /v3/pay-request` `POST /v3/reversals`
`b2pochi_payments`	`POST /v3/pochi` `POST /v3/reversals`
`b2b_payments`	`POST /v3/b2b-request-new` `POST /v3/reversals`
`account_api`	`GET /v3/wallet` `POST /v3/wallet` `GET /v3/wallet/status` `GET /v3/transactions` `GET /v3/channels` `POST /v3/channels` `GET /v3/account`

Reversals accept any payout scope at the door, then require the scope of the original payment (b2c_payments also covers wallet withdrawals). Fees and service-status endpoints need a valid key but no scope.