API och integrationer

Kelomos publika gränssnitt används med API-nycklar. Organisationens nycklar och webhookar hanteras under Inställningar → Plattform och säkerhet → Gränssnitt och webhookar. Din egen personliga nyckel skapar du i dina egna inställningar på fliken API-nycklar.

Två slags nycklar

• En personlig nyckel agerar med dina behörigheter och når högst lika långt som du själv. Nyckeln upphör när ditt medlemskap upphör. Varje användare kan skapa en egen.
• En tjänstenyckel är till för integrationer som ska fungera oberoende av en enskild person. Den har en namngiven Ägare – den medlem vars behörigheter nyckeln agerar med – och ägaren kan bytas senare med knappen Byt ägare; token, behörigheter och historik består. Tjänstenycklar skapas av administratören.

Skapa en nyckel

1. Tryck på Skapa nyckel (egen nyckel) eller Skapa tjänstenyckel (organisationen).
2. Ange Nyckelns namn och vid behov en beskrivning. För en tjänstenyckel väljs också Ägare.
3. Välj Nyckelns behörigheter. Endast de behörigheter nyckelns innehavare själv har går att välja. En personlig nyckel utan valda behörigheter når bara dina egna uppgifter; en tjänstenyckel kräver minst en behörighet.
4. Välj Giltighet (30 dagar, 90 dagar, 1 år eller utan förfall) och kryssa vid behov i Skrivskyddad.
5. Spara. Nyckelns värde börjar med kelomo_ och skickas i begäranden i huvudet Authorization: Bearer.

Värdet visas bara en gång. Kopiera det genast. Om värdet kommer bort kan du byta den egna nyckelns token med Byt token – den gamla gäller i 24 timmar till – eller skapa en ny nyckel.

Hantera nycklarna

Listan visar nyckelns början, skapelsedatum, senaste användning och antalet begäranden under sju dagar. Återkalla tar nyckeln ur bruk permanent. Om en nyckel närmar sig sitt förfall skickar Kelomo en avisering i förväg, så att du hinner förnya den före avbrottet.

Utgående webhookar

I avsnittet Utgående webhookar skickar Kelomo valda händelser till den adress du anger – till exempel publicerade pass, fakturahändelser och frånvarobeslut.

1. Ange Adress (https).
2. Välj Format: JSON (signerad) för integrationer, Slack eller Microsoft Teams för färdiga meddelanden till kanalens incoming webhook-adress. För Slack och Teams väljs också Meddelandespråk.
3. Välj Händelser – som standard är alla valda.
4. Tryck på Lägg till webhook. För JSON-formatet visas signeringshemligheten (X-Kelomo-Signature) – även den bara en gång.

Radens åtgärder: Testa skickar ett testmeddelande, Pausa och Fortsätt stoppar leveranserna, Byt hemlighet roterar signeringshemligheten (den gamla gäller i 24 timmar till). Formatet kan inte bytas i efterhand – skapa vid behov en ny webhook.

Visa leveranser öppnar leveransloggen. En misslyckad leverans försöks om automatiskt; raden visar tiden för nästa försök, och leveransen kan skickas om manuellt med Skicka igen. Om en leverans slutgiltigt inte går fram får du en avisering.

Anslutna appar

AI-assistenter och andra färdiga appar ansluts genom inloggning, inte genom att kopiera en nyckel: i appen väljer man Kelomo, användaren loggar in, väljer organisation och godkänner de begärda rättigheterna. Appen arbetar med godkännarens rättigheter och får aldrig mer än hen själv har — om appen begär mer omfattande rättigheter säger godkännandeskärmen det i förväg.

Anslutningarna visas under Inställningar → Gränssnitt och webhookar i avsnittet Anslutna appar: vilken app, med vems rättigheter och när den senast användes. Dina egna anslutningar ser du också i dina egna inställningar på fliken API-nycklar. Avsluta anslutning bryter den omedelbart — appens nästa anrop går inte igenom. Ett lösenordsbyte eller en lösenordsåterställning avslutar alla anslutna appar på ditt konto.

En ansluten app får aldrig rätt att hantera organisationens inställningar, fakturering eller API-nycklar. Om en integration behöver göra sådant krävs en tjänstenyckel som en människa skapar själv.

API-dokumentation och MCP

Utvecklardokumentationen finns på kelomo.fi/developers: autentisering, händelser, felkoder, användningsgränser och OpenAPI-beskrivningen. Där finns också MCP-guiden och OAuth-guiden. MCP-anslutningen fungerar på båda sätten: klienten loggar in (rekommenderas) eller använder en kelomo_-nyckel. I båda fallen agerar AI-klienten inom referensens behörigheter.

Om något går fel

Nyckelns värde finns inte längre kvar. Värdet visas inte på nytt. Byt den egna nyckelns token eller skapa en ny nyckel och återkalla den gamla.

Tjänstenyckeln svarar med fel 401. Om nyckelns ägare har inaktiverats slutar nyckeln fungera. Tilldela nyckeln en annan medlem med knappen Byt ägare.

Begäran svarar med fel 403. Nyckelns behörigheter räcker inte, eller så är nyckeln Skrivskyddad. Skapa en ny nyckel med de behörigheter som behövs.

En webhookleverans står som “Permanent misslyckad”. Kontrollera mottagarens adress och svar i leveransloggen, åtgärda mottagaren och tryck på Skicka igen.