Build / API keys
API keys
Every request sends a secret key in the Authorization header. The key's prefix shows which environment it belongs to.
Sending the key
Authorization: Bearer vk_live_8d1Kx...
| Prefix | Host | Money |
|---|---|---|
vk_test_ | https://sandbox.vukia.app | Simulated |
vk_live_ | https://api.vukia.app | Real |
A key only works on its own host. A test key sent to production, or a live key sent to the sandbox, is rejected with 401 wrong_environment. The message tells you which host to use. Keys are 40 characters long and contain only letters, digits, _ and -.
Keeping keys safe
- Server side only. A live key can start real M-Pesa charges. Never put it in a mobile app, browser JavaScript, a POS terminal's local storage or a public repository. Terminals call your server, and your server calls Vukia.
- Keep it with your other secrets. Use an environment variable or your secret manager, not a config file under version control.
- Keep it out of logs. Do not write request headers to logs or error trackers without removing
Authorization. - We cannot show you a key again. Vukia stores only a one-way hash of each key. If a key is lost, ask for a replacement.
How production keys are delivered
We never send a live key in an email. When your production account is approved:
- We email your technical contact a one-time link to
https://api.vukia.app/claim/…. The link expires after 72 hours. - Opening the link does not reveal the key. Email security scanners often open links automatically. The page waits until a person presses Reveal key.
- The key is shown once. Copy it straight into your secret store. After that, the link stops working and the key cannot be retrieved.
If the link expires, or the key was not copied, email [email protected] from your registered contact address and we will send a new link.
Replacing a key
Ask for a replacement if a key may have leaked, if someone who had it leaves, or as routine practice. Email [email protected] from your registered contact address.
Each account has one live key. The old key stops working as soon as we create the new link, not when you open it. Agree a time with us, have your deployment ready, and claim the new key straight away. Orders already created are not affected. They keep settling and their webhooks are still delivered.
A sandbox key cannot be replaced. Create a new sandbox account from the quickstart instead.
Authentication errors
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer … header was sent. |
| 401 | wrong_environment | A test key was sent to production, or a live key to the sandbox. |
| 401 | invalid_api_key | The key does not exist or has been replaced. |
| 403 | account_disabled | The account has been suspended. Email [email protected]. |