Manage API keys for integrations

If you want to integrate another system with Your HR Toolkit (a payroll provider, a custom internal tool, a reporting dashboard), API keys are the way to authenticate the integration. The Settings area lets you generate, scope, and revoke keys.

Open API Keys

1. On the left hand sidebar, click Settings.
2. Open the API Keys area.

You’ll see a list of existing keys for your organisation, with their scopes, creation date, and status (active or revoked).

Generate a key

1. Click to create a new key.
2. Pick the scopes the key needs:
   • read:employees — read employee records
   • read:leave — read leave balances and requests
   • read:performance — read performance review and goal data
   • (other scopes as the platform’s external API expands)
3. Optionally set an expiration date. Without one, the key never expires.
4. Click to generate.

The platform shows the key value once. Copy it now and store it somewhere safe (a password manager or your team’s secret store). You will not be shown the key again.

Why you only see the key once

The platform stores only a SHA-256 hash of the key, not the key itself. The hash is enough to verify a key when it’s used to make API calls, but it’s not enough to recover the key if you lose it. This is a deliberate security trade-off: even if the platform’s database were somehow exposed, the keys themselves wouldn’t be in it.

If you lose a key, you can’t recover it. Generate a new one and revoke the old one.

Use the key

Each API request to the platform’s external endpoints passes the key in an Authorization header:

Authorization: Bearer yhrtk_xxxxxxxxxxxxxxxxxxxx

The exact endpoints available depend on the scopes you’ve granted. For the current external API documentation, email support@yourhrtoolkit.com.au and we’ll send you the relevant endpoint reference.

Scopes are read-only

The current scopes are read-only. The platform doesn’t currently expose write operations via API keys. This is by design: most integrations need to read your platform data into another system, not modify your platform data from outside.

If you need a write integration, contact us to discuss what you’re trying to do — we can usually find a safer pattern (e.g. workflows fired by webhooks rather than direct API writes).

Revoke a key

If a key is compromised, no longer needed, or used by someone who’s left:

1. Find the key in the list.
2. Click to revoke.

The revocation is immediate. Any system using that key starts getting 401 Unauthorized errors. The key record stays in the audit trail (for compliance), it’s just inactive.

Best practices

• One key per integration. Don’t share a single key across multiple systems. If one is compromised, you don’t have to scramble to update everything.
• Minimum scopes. Grant only the scopes the integration genuinely needs.
• Set expiration on temporary integrations. A key for a consultant’s project should expire when the project ends.
• Rotate periodically. For long-running integrations, generate a new key annually and update the integration to use it. Then revoke the old one.

Permissions

Generating, viewing, and revoking API keys is org admin only.