Authentication
The PayKH API authenticates with a secret API key sent as a Bearer token. Each key belongs to one store and one mode.
Authorization header
Authorization: Bearer bk_live_xxxxxxxxxxxxxxxxxxxxxTest vs live keys
| Prefix | Mode | Behaviour |
|---|---|---|
bk_test_ | Test | No real money. Use simulate to drive outcomes. |
bk_live_ | Live | Real Bakong settlement. Available once your account is activated. |
The mode is determined by the key, not the URL — the base URL is always the same.
Creating & managing keys
Create keys in the dashboard under a store’s API keys tab. You can label, rotate, and revoke keys there. The full secret is shown only once — only a prefix is stored, so a leaked key is revoked, never recovered.
⚠️ Never expose secret keys
Secret keys grant full access to a store’s payments. Keep them server-side, in environment variables or a secrets manager. If a key leaks, rotate it immediately from the dashboard.
Roles & permissions
Dashboard access is governed by team roles — Owner, Developer, and Analyst — plus attribute-based rules (e.g. minting a bk_live_ key requires the Owner role). API keys themselves always act with full store scope.
Rate limits
| Scope | Limit |
|---|---|
/v1/* per API key | 100 requests / 10 seconds |
| Auth endpoints per IP | 10 requests / 60 seconds |
Exceeding a limit returns 429 with error code rate_limit_exceeded.