Authentication

Send one secret key as a bearer token:

Authorization: Bearer mkp_test_…

A key is mkp_test_ or mkp_live_, then 52 characters from A-Z and 2-7. Any other shape is refused before a lookup.

Keep the key on your server

Store it in a secret store or an environment variable. Do not put it in a web page, a mobile app, a public repository, or a URL.

The browser must not hold the key. The browser must not send the amount. Kahawa reads the key only inside a Pages Function.

Get a key

Open the hub. Open API Integrations. Open the Keys tab.

Action	PIN	Result
Create Key	Yes	The hub shows the key once. It stores a hash.
Replace Key	Yes	The same button, when a key exists. The old key can work for up to 1 minute.
Revoke	No	The key can work for up to 1 minute.

An account has one live key. Create Key on an account that already has a key replaces that key. There is no gap with two live keys, and no gap with none.

If you lose the key, create a new one. The lost key stops working.

The table shows the prefix, the last four characters, the create time, and the last use time.

What a key can do

A key can	A key cannot
POST /checkouts that pay its owner	Send money out
GET /checkouts/:id for those checkouts	Read the wallet, balance, or history
	Call any other MOOKHPay route

A leaked key can open checkouts that pay you. Revoke it.

A checkout belongs to the account that created it. Another account's id returns 404 and code 2783.

The cache lasts 60 seconds

MOOKHPay caches each key result for 60 seconds. A replaced or revoked key can still work during that minute. A refused key is cached for the same minute.

Errors

HTTP	Code	Meaning
401	2781	Missing, malformed, unknown, or revoked key
503	2782	The key service did not answer. Retry soon

Invalid JSON, fields, or headers return 400 and code 1701 before the key check. A 400 does not show that the key is valid. See Errors.