How to Issue and Manage Payroll API Keys in CrmLeaf
Payroll edition add-on. The Payroll API is a paid, per-company add-on that must be switched on for your company by whoever operates your CrmLeaf instance, and managing it requires the manage_payroll_engine_api…
Availability: Payroll edition add-on. The Payroll API is a paid, per-company add-on that must
be switched on for your company by whoever operates your CrmLeaf instance, and managing it requires the
manage_payroll_engine_api permission. A usage plan must also be assigned to your company before keys
can be used at volume.
What's New NEW
R26.10 · Oct 2026The Payroll edition now includes a programmatic Payroll API: your developers or partners can integrate payroll into their own systems using per-company API keys with scoped access and metered usage plans, all administered from CrmLeaf.
Overview
The Payroll API lets another system — your own software, or a partner's — read and write payroll-related data without anyone using the CrmLeaf screens. Access is controlled by API keys that your company creates, limits to specific kinds of data, and can rotate or revoke at any time.
This article covers what you manage inside CrmLeaf: keys, scopes, usage plans and the developer portal. It does not document the individual API requests, which are served by a separate payroll engine — see Important Notes.
How It Works
An Administrator creates a key in the Payroll API area of Settings, chooses live or sandbox mode, and chooses which scopes it carries. The key is shown once. The developer sends it with each request, and usage is counted against the usage plan assigned to your company.
Create key → Choose live or sandbox → Choose scopes → Copy the key once → Developer integrates → Monitor usage → Rotate or revoke
- Per-company keys. Each company manages its own keys from a self-service key portal under Settings.
- Create, rotate and revoke. Rotation keeps a record of which key replaced which, so changes can be traced; revoking stops a key immediately.
- Live and sandbox. A key is either live or sandbox, so integration can be built and tested without touching real payroll data.
- Shown once, stored hashed. The key value is displayed only when it is created, and CrmLeaf stores only a hashed form. If it is lost, rotate it — it cannot be viewed again.
- Optional request-signing secret. A key can carry a signing secret so requests can be verified as coming from the key's holder.
- Scoped access. Each key carries abilities across four areas — organizations, employees, payroll and statutory data — each as read or write. A key can only do what its scopes allow.
- Metered usage plans. A plan defines quotas per time window (minute, hour, day, week or month), whether the limit is soft or hard, an overage cap and usage-threshold alerts. A plan is assigned to your company by whoever operates your CrmLeaf instance, and the developer sees the limits in the standard rate-limit headers returned with responses.
- Developer portal. API consumers have their own signup and login funnel.
Who Can Use This Feature?
Administrator
- Create, rotate and revoke the company's Payroll API keys.
- Choose live or sandbox mode and the scopes for each key.
- Review usage against the assigned plan.
Managing Payroll API keys requires the manage_payroll_engine_api permission. Not
every Administrator has it by default.
Prerequisites
- The Payroll edition, with the Payroll API add-on switched on for your company.
- A usage plan assigned to your company.
- The
manage_payroll_engine_apipermission on your role. - A secure place for the developer to store the key, because it is a credential.
- A clear decision on which kinds of data the integration needs, so each key gets the narrowest scopes.
For Administrators
Step 1: Open the Payroll API area
What to do: Open the Payroll API page in Settings.
What to verify: You see the key list for your company and the usage plan assigned to it. If the page is missing, the add-on has not been switched on, or your role lacks the permission.
Step 2: Create a sandbox key first
What to do: Create a key in sandbox mode, give it a name that identifies the integration, and choose only the scopes it needs — for example employees read, with no write access.
What to verify: The key appears in the list in sandbox mode with the scopes you chose.
Step 3: Copy the key and hand it over securely
What to do: Copy the key as soon as it is shown and pass it to the developer through a password manager or secrets store. Do not send it by email or paste it into a ticket.
What to verify: The developer has the key stored securely. Remember that it cannot be displayed again.
Step 4: Move to a live key when testing is complete
What to do: After the integration works in sandbox, create a separate live key with the same minimum scopes.
What to verify: The live key is listed in live mode, and the sandbox key is revoked if it is no longer needed.
Step 5: Monitor usage and rotate or revoke
What to do: Watch usage against the plan's quotas and alert thresholds. Rotate a key on a regular schedule, when a developer leaves, or if it may have been exposed; revoke it when the integration ends.
What to verify: The old key stops working after rotation or revocation, and the new key works.
Field and Option Reference
| Field / Option | Description | Required |
|---|---|---|
| Key name | A label that identifies where the key is used, so the right one can be rotated or revoked. | Yes |
| Mode | Live or sandbox. | Yes |
| Scopes | Read or write ability across organizations, employees, payroll and statutory data. | Yes |
| Signing secret | Optional secret used to verify that a request was signed by the key's holder. | No |
| Usage plan | Quotas per window, soft or hard enforcement, overage cap and alert thresholds. Assigned to the company, not chosen per key. | Set for the company |
Expected Result
Your company has one or more named Payroll API keys, each in live or sandbox mode and limited to the scopes it needs. The developer's integration authenticates with the key, usage is counted against your plan, and you can rotate or revoke any key without affecting the others.
Important Notes
- Menu names and their position can differ between product editions and can be customised for your account, so your sidebar may not match these paths exactly. Use Search or your Quick Access items if you cannot find a screen.
- CrmLeaf administers the API; a separate payroll engine serves it. Keys, scopes, usage plans and the developer portal are managed in CrmLeaf, but the requests that run payroll or return payslips and salaries are handled by a separate payroll engine. Confirm the live endpoint list with your CrmLeaf contact before promising specific endpoints to a developer.
- A Payroll API key is not a personal access token. Personal access tokens connect AI assistants and act as one user; Payroll API keys belong to the company and carry their own scopes. See How to Create Personal Access Tokens.
- Give every key the narrowest scopes it needs. Prefer read-only scopes unless the integration must write.
- Payroll data is sensitive. Treat a key as a credential, and revoke it as soon as it is no longer needed.
- If a usage limit is set to hard enforcement, requests beyond the quota are refused until the window resets, so an integration should handle that response.
Common Scenarios
Example: syncing employees to an in-house system. A company's developer needs employee records in an internal tool. The Administrator creates a sandbox key with employees read only, tests the integration, then creates a live key with the same single scope.
Example: a departing developer. A contractor who held a live key leaves the project. The Administrator rotates the key, gives the new one to the remaining developer, and confirms the old key no longer works.
Troubleshooting
| Issue | Possible Cause | Resolution |
|---|---|---|
| The Payroll API page is missing | The add-on is not switched on, or your role lacks manage_payroll_engine_api | Ask whoever operates your CrmLeaf instance to enable it, and ask your Administrator for the permission. |
| A request is refused for insufficient access | The key does not carry the needed scope | Create a new key with the required scope; do not widen scopes on a key already shared widely. |
| Requests are refused after working earlier | The usage quota is exhausted under hard enforcement, or the key was revoked or rotated | Check usage against the plan and the key's status in the key list. |
| The key value cannot be found | It is shown only once and stored hashed | Rotate the key and give the developer the new value. |
| Sandbox calls return no real data | A sandbox key is meant for testing | Use a live key when you need real payroll data. |
Frequently Asked Questions
Can I see an API key again after creating it?
No. It is displayed once and only a hashed form is stored. Rotate the key if the value is lost.
What is the difference between live and sandbox?
Sandbox keys are for building and testing an integration; live keys work against real payroll data.
What can a key do?
Only what its scopes allow. Scopes cover organizations, employees, payroll and statutory data, each as read or write.
Who sets the usage limits?
A usage plan is assigned to your company by whoever operates your CrmLeaf instance. The plan defines the quotas per time window and whether limits are soft or hard.
Which endpoints can my developer call?
Related Articles
Our support team answers on business days. Reference PAY-16 so we can jump straight in.