Every request to the KalHR API carries an API key. A key belongs to one organisation, acts only for that organisation, and can do exactly what it was given access to when it was created.
How keys work
- One key per system. Create a separate key for each system that connects (your accounting package, your identity provider, a reporting job). Each can then be given only what it needs, and revoked without affecting the others.
- Created by a person, in KalHR. An administrator creates keys under Settings → API keys. There is no API for creating keys.
- Shown once. KalHR stores only a fingerprint (a SHA-256 hash) of the key, so it can't show it again. A lost key is revoked and replaced.
- Recognisable. Every key starts with
kal_live_, so a leaked key is easy to spot, for you and for secret-scanning tools. A key looks likekal_live_ab2cd3ef4gh5_…. - Recorded. Changes made with a key appear in KalHR's audit log under the key's name, for example API: Accounting system.
Send the key
Put the key in the Authorization header of every request, as a bearer token:
Authorization: Bearer kal_live_…
If your tool can't set Authorization, send it in X-Api-Key instead:
X-Api-Key: kal_live_…
Call the API from your servers only. Anyone who holds a key can do whatever it allows, so it must never be sent to a browser or shipped in a mobile app.
Check a key
GET v1/integrations/api-keys/me answers with the key's name, organisation and permissions. Any key can call it.
curl "https://api.kalhr.com/v1/integrations/api-keys/me" \
-H "Authorization: Bearer $KALHR_API_KEY"The answer is described in the reference.
Create a key
This is done in KalHR by someone with the Manage API Keys permission. If that isn't you, send these steps to your KalHR administrator.
- Open Settings → API keys and select Create key.
- Give it a Name that says which system will use it, such as Accounting system. Add a Description if it helps: who owns the system, what it's for.
- Under Access, choose a level for each module the system needs, and leave the rest at No Access:
- View: read records and reports.
- Manage: also create, edit and carry out day-to-day actions.
- Admin: also configuration and deletion.
- Optionally choose an Expires date. After that day the key stops working. Use one for short projects and contractors.
- Select Create key, copy the key into the system's secret store, and select I've stored it.
An organisation can have up to 20 active keys.
What a key can do
The API reference names the access each endpoint needs, as it appears when creating a key:
| Access on the key | Lets the key read |
|---|---|
| Employee Management: View | Employees, companies and departments |
| Leave: View | Leave requests, leave balances and leave types |
| Attendance: View | Attendance records, absence reports, excused days and holidays |
| Payroll: View | Payroll runs and each employee's pay in them, and salaries in employee records |
Three rules apply whatever access is chosen:
- Never more than its creator. A key can't be given access its creator's own role doesn't have; KalHR refuses to create it.
- Never money or access control. Paying salaries or loans, refunds, and managing users, roles, teams, API keys and webhooks are removed from every key. A person always does those in KalHR.
- Only the public API. A key works only on the endpoints in the API reference. Any other
endpoint answers
403, even if the key's access would cover it.
Rotate a key
To replace a key, for example when someone who saw it leaves:
- Create a new key with the same access.
- Move your system to the new key and check that it works.
- Revoke the old key.
Changing a key's name, description, access or expiry (the pencil on the key) keeps the key itself, so the system using it carries on working. Changes reach every KalHR server within a minute.
Revoke a key
Select Revoke on the key and confirm. Requests with it are refused within a minute, with 401. Revoking can't be
undone. The key stays on the list, marked Revoked, so the audit log still names it.
Plans
API keys and webhooks are part of the Premium and Enterprise plans. While KalHR's free usage policy lasts, every organisation can use them. If an organisation moves to a plan without them, nothing is deleted: keys are refused and webhook events wait, and both carry on when the plan includes them again.
Related
- Errors: what
401and403mean and what to do - Security checklist
