Authentication and scopes
Issue a company-scoped credential, grant only what the task needs and keep rotation deliberate.
Choose your authentication flow
Company API operations use X-Api-Key. Each key belongs to one company and has a verified Test or Live mode. The Kola OIDC flow instead uses its registered client, PKCE exchange and OIDC bearer access token; it does not authenticate with a company API key.
All company API requests use https://api.kuahr.com/v1. Choose a Test or Live key with the appropriate scopes. Upgrade guidance covers existing keys.
Issue and use a key
Open Developer → API keys in the Kua dashboard. Select the company and intended mode, obtain the required permission/identity confirmation and issue a named integration key with the smallest necessary grants.
The secret is shown once. Store it in your server-side secret manager. An empty scope list grants no scoped API access.
curl --fail-with-body https://api.kuahr.com/v1/payroll/runs \
-H "X-Api-Key: $KUA_API_KEY"This read requires a Test key with payroll:read. API keys are not browser credentials and must not be embedded in client-side bundles.
Scopes
| Scope | Permits |
|---|---|
payroll:read | List runs in the key’s Live or Test partition |
payroll:write | Create payroll drafts; does not authorise disbursement |
employees:write | Create employees; there is no public employee-list / employees:read contract |
events:read | Read the company event timeline with a Live key |
test-data:clear | Clear only the company’s Test records, using either an authorised Live or Test key |
leave:read / leave:write | Read / mutate leave resources, respectively |
advances:read / advances:write | Read / request or decide advances, respectively; approval can move money |
performance:read / performance:write | Read / mutate performance resources, respectively |
webhooks:read | Inspect endpoints, deliveries and retained history |
webhooks:write | Register/delete endpoints and ping; also permits inspection |
webhooks:replay | Inspect webhook records and replay an eligible exhausted delivery |
* | All scopes, only in supported modes and subject to endpoint policy |
Read grants do not imply writes or Test-data deletion. Events and add-ons have no isolated Test partition: sufficiently scoped Test reads receive 409 TEST_MODE_UNSUPPORTED; their unsupported writes and the webhook family retain 400. Missing event/add-on read grants return 403 INSUFFICIENT_SCOPE first. Mode matrix.
Company modules no longer require the retired Settings → Modules enable/request/approval flow. Scope permission still does not replace workspace approval, eligibility, country/provider support or other endpoint rules. Dashboard JWT sessions use their own company capabilities and Owner-controlled Admin defaults; issuing a scoped integration key does not change those roles.
Rotate or revoke
Key rotation and revocation are authenticated dashboard-management actions, outside the public SDK contract. Rotate deliberately from the matching company’s API-key settings. Rotation revokes the old secret immediately and issues a new credential with the same name, scopes and mode. It does not add missing grants; issue the intended scoped key instead.
Before rotation, reconcile writes with unknown outcomes. Idempotency receipts are scoped to credential identity, so a replacement key is a new namespace. Update the application’s secret, verify a read, monitor the transition, and retain the responsible actor’s audit record. If the one-time response was lost, inspect key state and deliberately issue/rotate again through the administrator; never assume you can retrieve the hidden secret.
Revoke unused or compromised keys through the authorised dashboard. Stop new work and reconcile in-flight outcomes; revocation does not undo completed actions.
Keep secrets out of the wrong places
Use one named key per integration, redact request headers from logs and keep secrets out of source, browser storage, screenshots and support messages. The API reference does not persist authentication; clearing its form is not server-side revocation. Only enter a live credential after checking the host and intended operation.
November 2026 scope upgrade
The scope and Test-isolation rules above are enforced at https://api.kuahr.com as of 8 November 2026. Test and Live keys use this same address.
Earlier restricted/empty-scope keys must be reissued with the appropriate payroll:read, events:read and/or test-data:clear grants. Rotation preserves scopes. Existing * keys retain authorised access only in supported modes. Test payroll is partitioned; event/add-on reads refuse Test keys instead of exposing live records. Isolated add-on Test fixtures remain unavailable. Official SDKs are published in npm and PyPI; see SDK setup.
Done when: the correct company, key mode and grants are recorded, the secret is stored server-side and the intended scoped read succeeds. Continue to quickstart or your selected API journey.