Build on Kelomo

Mint an API key

To try things out, open Settings → your own API keys in Kelomo and create a personal key. Pick the capability scopes the integration needs (a key with no scopes reaches only your own /v1/me/* data), optionally mark it read-only, and set an expiry — the default is one year. The kelomo_… token is shown once; store it in a secret manager.

For an integration that runs unattended, an admin mints a service key in Settings → API access instead: it names an owner member and can be handed to somebody else when that person leaves. See Authentication for the difference.

Make your first call

GET /v1/me/entitlements works with any key, whatever its scopes — it returns the modules enabled for your organisation, so it doubles as a connection test.

curl https://api.kelomo.fi/v1/me/entitlements \
  -H "Authorization: Bearer kelomo_YOUR_KEY"

const response = await fetch('https://api.kelomo.fi/v1/me/entitlements', {
  headers: { Authorization: `Bearer ${process.env.KELOMO_API_KEY}` },
});
if (!response.ok) throw new Error(`Kelomo API returned ${response.status}`);
const entitlements = await response.json();
console.log(entitlements);

A 200 means the key authenticates. A 401 means the token is wrong, revoked or expired — see Errors for how failures are shaped.

Subscribe to your first webhook

Webhooks push events to your endpoint as they happen. Subscribing requires the integrations.manage scope on the key (or use Settings → API access in the UI).

curl -X POST https://api.kelomo.fi/v1/webhooks \
  -H "Authorization: Bearer kelomo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/kelomo",
    "events": ["workday.approved"]
  }'

{
  "id": "1f6c2c1e-9d1a-4b7e-a1c4-6a0f6a4a2b10",
  "secret": "whsec_…"
}

The secret signs every delivery and is shown once. Verify signatures and handle retries as described in Webhooks.

Or skip the code entirely

Zapier connects with an API key and uses the same webhook subscriptions as triggers. n8n works out of the box with its generic HTTP Request and Webhook nodes. For Power Automate, build a custom connector from the Swagger 2.0 download.