Authentication - Kua API

The Kua API authenticates with an API key. Issue one from Settings → API keys in the dashboard (issuing a key requires two-factor confirmation).

Using your key

Send the key in the X-Api-Key header on every request. The SDKs do this for you once you construct the client:

curl https://api.kuahr.com/v1/payroll/runs \
  -H "X-Api-Key: kua_live_your_key_here"

import { Kua } from "@kua/node";

const kua = new Kua({ apiKey: process.env.KUA_API_KEY! });

import os
from kua import Kua

kua = Kua(api_key=os.environ["KUA_API_KEY"])

<?php
$ch = curl_init("https://api.kuahr.com/v1/payroll/runs");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-Api-Key: " . getenv("KUA_API_KEY")],
]);
$response = curl_exec($ch);

The full secret is shown only once, when the key is created. Store it in your secret manager immediately. If you lose it, rotate the key.

Scopes

Keys carry scopes that gate what they can do. Read endpoints need no scope; write endpoints require the matching scope:

Scope	Grants
`employees:write`	Create employees (`POST /v1/employees`)
`payroll:write`	Create payroll runs (`POST /v1/payroll/runs`)
`leave:read`	Read leave types, requests, and balances
`leave:write`	Create/approve/reject/cancel leave, manage types & allocations
`advances:read`	Read salary advances
`advances:write`	Request/approve/reject salary advances
`performance:read`	Read objectives, appraisals, and promotions
`performance:write`	Manage objectives, appraisals, and promotions
`*`	All scopes

A request with a key that lacks the required scope returns 403 with code INSUFFICIENT_SCOPE.

The add-on scopes (leave:*, advances:*) also require the company to have that add-on enabled. If it isn’t, those endpoints return 403 MODULE_NOT_ENABLED regardless of the key’s scopes — a company admin enables it in Settings → Modules.

Rotating a key

Rotate from the dashboard (or POST /api-keys/{id}/rotate) to revoke the old secret and mint a new one with the same name and scopes — so you can roll a credential without reconfiguring the integration. The old secret stops working immediately.

Keeping keys safe

Never embed a key in client-side code or commit it to source control. Keys begin with kua_ so secret scanners can spot leaks.
Use a separate key per integration so you can revoke one without affecting the others.
Revoke unused keys from the dashboard.

​Using your key

​Scopes

​Rotating a key

​Keeping keys safe

Using your key

Scopes

Rotating a key

Keeping keys safe