Skip to main content
Every request to the Kulmi Pay API must be authenticated. Most endpoints use a short-lived Bearer token that you obtain by exchanging your application credentials. Checkout and collection endpoints additionally accept a Public Key that you pass directly in the request body or as a header.

​
Bearer token (OAuth2 password grant)

Use this method for all standard API calls — M-Pesa deposits, disbursements, wallet operations, webhooks, and more.

​
Request a token

Send a POST request to /api/token/ with your API caller credentials in the request body and your application credentials as HTTP Basic auth. 
curl -X POST \
  -d "grant_type=password&username=<API-CALLER-USERNAME>&password=<API-CALLER-PASSWORD>" \
  -u "<CLIENT-ID>:<CLIENT-SECRET>" \
  https://app.kulmipay.com/api/token/

​
Token request parameters

ParameterLocationDescription
grant_typeBodyAlways password
usernameBodyYour API caller username
passwordBodyYour API caller password
CLIENT-IDBasic auth usernameYour application’s Client ID
CLIENT-SECRETBasic auth passwordYour application’s Client Secret

​
Use the token in requests

Include the token in the Authorization header of every subsequent request: 
curl --request GET \
  --url https://app.kulmipay.com/api/wallets/ \
  --header 'Authorization: Bearer <access_token>'
Tokens expire after a period of inactivity. When a request returns a 401 Unauthorized response, request a new token using the same flow above.

​
Public key

Your Public Key identifies your business for checkout and collection requests. You can find it in your dashboard under API Applications. Public keys follow the format ISPubKey_live_... in production and ISPubKey_test_... in the sandbox. Pass your public key in one of two ways: Option 1 — Request body: 
{
  "public_key": "ISPubKey_live_xxxxxxxxxxxxxxxx",
  "amount": "100",
  "currency": "KES"
}
Option 2 — Request header: 
X-KULMI-PUBLIC-API-KEY: ISPubKey_live_xxxxxxxxxxxxxxxx
When testing in the sandbox, use ISPubKey_test_... credentials. Using a live public key against sandbox.kulmipay.com will return an authentication error.

​
Common authentication errors

StatusErrorWhat to do
401 UnauthorizedInvalid credentialsCheck your username, password, Client ID, and Client Secret
401 UnauthorizedToken expiredRequest a new access token
400 Bad RequestInvalid API credentialYour public key or secret key is malformed or from the wrong environment
400 Bad RequestInvalid API credential for live environmentYou’re using a test key against the live API, or vice versa

​
Keeping credentials secure

  • Never expose your Client Secret or API caller password in client-side code, public repositories, or logs.
  • Store credentials in environment variables or a secrets manager, not in source files.
  • If a credential is compromised, rotate it immediately from the API Applications section of your dashboard.