Authentication

Every request to the Your HR Toolkit external API authenticates with an API key. Keys are organisation-scoped and carry a set of permissions (scopes) that determine what they can read.

Org admins generate API keys from Settings then API Keys inside the platform. See Manage API keys for integrations for the full walkthrough.

Keys start with yhrtk_ and are returned exactly once at creation. The platform stores only a SHA-256 hash, so a lost key cannot be recovered. Store it in a password manager or secret store immediately.

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer yhrtk_xxxxxxxxxxxxxxxxxxxx

Example with curl:

curl https://platform-yhrtk-api.annabelle-f10.workers.dev/api/external/employees \
  -H "Authorization: Bearer yhrtk_xxxxxxxxxxxxxxxxxxxx"

Example with JavaScript fetch:

const res = await fetch(
  'https://platform-yhrtk-api.annabelle-f10.workers.dev/api/external/employees',
  { headers: { Authorization: `Bearer ${process.env.YHRTK_API_KEY}` } },
);
const { data, pagination } = await res.json();

Each API key carries one or more scopes. Each endpoint requires a specific scope; if your key doesn't have it, the request returns 403. Available scopes:

• read:employees — read employee records
• read:leave — read leave balances and requests
• read:performance — read performance review and goal data (no endpoints currently use this scope, reserved for future)

Grant the minimum scopes the integration genuinely needs. Don't ship a key with all scopes if it only reads leave balances.

Status	Meaning
401 Unauthorized	Missing, malformed, revoked, or expired API key.
403 Forbidden	API key is valid but doesn't have the scope this endpoint requires.
404 Not Found	The resource (e.g. employee ID) doesn't exist in your organisation.
429 Too Many Requests	Rate limit hit. Retry with exponential backoff.
500 Internal Server Error	Server-side problem. Retry with backoff. If persistent, report to support.

Keys can be revoked from the same Settings then API Keys page. Revocation takes effect immediately; any request with a revoked key returns 401.

For long-running integrations, rotate keys periodically: generate a new one, update your integration to use it, verify, then revoke the old one.

• One key per integration. Don't reuse a single key across multiple systems. If one is compromised, the blast radius is just that system.
• Store keys outside source control. Use environment variables, a secret manager, or your platform's config service. Never commit keys to a git repo.
• Set an expiration date for short-term integrations (consultants, project work). The key auto-expires when the work ends.
• Watch for unexpected 401s in your integration's error log. A sudden 401 may mean someone revoked the key (intentionally or not).