API and integrations

Kelomo’s public API is used with API keys. The organisation’s keys and webhooks are managed under Settings → Platform & security → API & webhooks. You create your own personal key in your own settings on the API keys tab.

Two kinds of keys

• A personal key acts with your permissions and reaches at most as far as you do. The key ends when your membership ends. Every user can create their own.
• A service key is for integrations that must work independently of any single person. It has a named Owner – the member whose authority the key acts with – and the owner can be changed later with Change owner; the token, permissions and history stay. Service keys are created by an admin.

Create a key

1. Press Create key (your own key) or Create service key (the organisation’s).
2. Give the Key name and, if you like, a description. A service key also needs an Owner.
3. Pick the Key permissions. Only the permissions the key’s holder has themselves are available. A personal key with no permissions selected reaches only your own data; a service key requires at least one permission.
4. Pick the Validity (30 days, 90 days, 1 year or no expiry) and tick Read-only if needed.
5. Save. The key’s value starts with kelomo_ and is sent in requests in the Authorization: Bearer header.

The value is shown only once. Copy it right away. If the value is lost, you can rotate your own key’s token with Rotate token – the old one remains valid for 24 hours – or create a new key.

Managing keys

The list shows the key’s prefix, creation date, last use and the request count over seven days. Revoke takes a key out of use permanently. When a key approaches its expiry, Kelomo sends a notification in advance so you can renew it before the outage.

Outgoing webhooks

In the Outgoing webhooks section, Kelomo posts the selected events to the URL you give – for example published shifts, invoice events and absence decisions.

1. Give the URL (https).
2. Pick the Format: JSON (signed) for integrations, Slack or Microsoft Teams for ready messages posted to the channel’s incoming-webhook URL. Slack and Teams formats also take a Message language.
3. Pick the Events – all are selected by default.
4. Press Add webhook. For the JSON format, the signing secret (X-Kelomo-Signature) is shown – it too only once.

Row actions: Test sends a test message, Pause and Resume stop deliveries, Rotate secret rotates the signing secret (the old one remains valid for 24 hours). The format cannot be changed afterwards – create a new webhook if needed.

Show deliveries opens the delivery log. A failed delivery is retried automatically; the row shows the next attempt, and you can resend a delivery by hand with Resend. If a delivery is given up on for good, you get a notification.

Connected apps

AI assistants and other off-the-shelf apps connect by signing in, not by copying a key: in the app you choose Kelomo, the user signs in, picks an organisation and approves the permissions asked for. The app acts with the approver’s permissions and never gets more than they hold themselves — if the app asked for more, the consent screen says so before they approve.

Connections appear under Settings → API and webhooks in the Connected apps section: which app, whose permissions it uses and when it last called. You can see your own connections in your own settings on the API keys tab as well. Disconnect ends a connection immediately — the app’s next call fails. Changing or resetting your password disconnects every app on your account.

A connected app is never granted the right to manage organisation settings, billing or API keys. An integration that has to do those things needs a service key, created by a person.

API documentation and MCP

The developer documentation lives at kelomo.fi/developers: authentication, events, error codes, rate limits and the OpenAPI spec. The MCP and OAuth guides are there too. An MCP connection works either way: the client signs in (recommended) or uses a kelomo_ key. Either way the AI client acts within the credential’s permissions.

If something goes wrong

You no longer have the key’s value. The value is not shown again. Rotate your own key’s token, or create a new key and revoke the old one.

A service key responds with 401. If the key’s owner has been deactivated, the key stops working. Assign the key to another member with Change owner.

A request responds with 403. The key’s permissions are not enough, or the key is Read-only. Create a new key with the permissions you need.

A webhook delivery shows “Permanently failed”. Check the receiver’s URL and response in the delivery log, fix the receiver and press Resend.