Test and Live keys
Use one API address. Your key selects Test or Live data and the actions it can access.
One API address
Every integration calls https://api.kuahr.com/v1. Both official SDKs use this address by default. Keep the same address when moving from Test to Live.
Create your keys in Developer → API keys for the intended company. Choose Test while building and Live when your integration is ready for live company data. Store the one-time secret securely.
Your key determines the mode
A verified kua_test_… key selects supported isolated Test records. A verified kua_live_… key accesses Live records for its company. Both need the relevant scopes. Changing a prefix yourself does not change a key’s mode or permissions.
Test mode currently supports employee creation, payroll drafts and payroll listing. Operations without isolated Test data are refused; they never fall back to Live records. Use an authorised Live key for those operations only when you are ready to work with live data.
| Operation | Required API-key scope | Test-key behavior |
|---|---|---|
| List payroll runs | payroll:read | Isolated Test runs only |
| Create employee | employees:write | Isolated Test employee |
| Create payroll draft | payroll:write | Isolated Test draft; eligible salary setup still required |
| Clear own company’s Test data | test-data:clear | Deletes Test records only; also callable with an authorised Live key |
| Read event timeline | events:read | 409 TEST_MODE_UNSUPPORTED |
| Read leave / advances / performance | Matching resource :read | 409 TEST_MODE_UNSUPPORTED |
| Write leave / advances / performance | Matching resource :write | 400 TEST_MODE_UNSUPPORTED |
| Webhook registration, reads, ping, deletion, history or replay | Appropriate webhooks:* grant | 400 TEST_MODE_UNSUPPORTED |
Missing read scopes return 403 INSUFFICIENT_SCOPE before the event/add-on Test-mode checks. * grants supported scopes; it cannot create isolated fixtures for an unsupported mode. Authentication explains the grants.
Reset Test data
Test records auto-purge after 14 days. For an intentional reset, use the same company’s scoped key:
curl --fail-with-body -X POST https://api.kuahr.com/v1/test-data/clear \
-H "X-Api-Key: $KUA_API_KEY"This is a deletion action: ensure no colleague still needs those fixtures before sending it. The scope is test-data:clear; payroll:write does not grant deletion. A successful response clears only the caller company’s Test records, never Live records or another company. Verify with the Test run list. If the response is lost, check the list before deliberately repeating the reset.
Continue safely
Use your first request for a read-only Test check and payroll drafts for isolated creation. To verify webhooks, obtain an authorised Live key and use a signed ping to your receiver. Complete the go-live checklist before switching your integration to a Live key.