API ja integraatiot

Kelomon julkista rajapintaa käytetään API-avaimilla. Organisaation avaimet ja webhookit hallitaan kohdassa Asetukset → Alusta ja turvallisuus → Rajapinta ja webhookit. Oman henkilökohtaisen avaimesi luot omissa asetuksissasi välilehdellä API-avaimet.

Kaksi avainlajia

• Henkilökohtainen avain toimii sinun oikeuksillasi ja ulottuu enintään yhtä pitkälle kuin sinä itse. Avain päättyy, kun jäsenyytesi päättyy. Jokainen käyttäjä voi luoda omansa.
• Palveluavain on integraatioille, joiden pitää toimia yksittäisestä henkilöstä riippumatta. Sillä on nimetty Omistaja – jäsen, jonka valtuudella avain toimii – ja omistajan voi vaihtaa myöhemmin painikkeella Vaihda omistaja; token, oikeudet ja historia säilyvät. Palveluavaimia luo pääkäyttäjä.

Luo avain

1. Paina Luo avain (oma avain) tai Luo palveluavain (organisaatio).
2. Anna Avaimen nimi ja halutessasi kuvaus. Palveluavaimelle valitaan myös Omistaja.
3. Valitse Avaimen oikeudet. Valittavana ovat vain oikeudet, jotka avaimen haltijalla itsellään on. Henkilökohtainen avain ilman valittuja oikeuksia yltää vain omiin tietoihisi; palveluavain vaatii vähintään yhden oikeuden.
4. Valitse Voimassaolo (30 päivää, 90 päivää, 1 vuosi tai ei vanhene) ja rasti tarvittaessa Vain luku.
5. Tallenna. Avaimen arvo alkaa kelomo_, ja se lähetetään pyynnöissä otsakkeessa Authorization: Bearer.

Arvo näytetään vain kerran. Kopioi se heti talteen. Jos arvo hukkuu, oman avaimen tokenin voi vaihtaa painikkeella Vaihda token – vanha toimii vielä 24 tuntia – tai luoda uuden avaimen.

Avainten hallinta

Listalla näkyy avaimen alkuosa, luontipäivä, viimeisin käyttö ja pyyntömäärä seitsemältä päivältä. Mitätöi poistaa avaimen käytöstä pysyvästi. Vanhenevasta avaimesta Kelomo lähettää ilmoituksen etukäteen, jotta ehdit uusia sen ennen katkoa.

Lähtevät webhookit

Osiossa Lähtevät webhookit Kelomo työntää valitut tapahtumat antamaasi osoitteeseen – esimerkiksi vuorojen julkaisut, laskutapahtumat ja poissaolopäätökset.

1. Anna Osoite (https).
2. Valitse Muoto: JSON (allekirjoitettu) integraatioille, Slack tai Microsoft Teams valmiiksi viesteiksi kanavan incoming webhook -osoitteeseen. Slack- ja Teams-muodoille valitaan myös Viestin kieli.
3. Valitse Tapahtumat – oletuksena kaikki ovat valittuina.
4. Paina Lisää webhook. JSON-muodolle näytetään allekirjoitussalaisuus (X-Kelomo-Signature) – sekin vain kerran.

Rivin toiminnot: Testaa lähettää testiviestin, Keskeytä ja Jatka pysäyttävät toimitukset, Vaihda salaisuus kierrättää allekirjoitussalaisuuden (vanha toimii vielä 24 tuntia). Muotoa ei voi vaihtaa jälkikäteen – luo tarvittaessa uusi webhook.

Näytä toimitukset avaa toimituslokin. Epäonnistunutta toimitusta yritetään automaattisesti uudelleen; rivillä näkyy seuraavan yrityksen aika, ja toimituksen voi lähettää käsin uudelleen painikkeella Lähetä uudelleen. Lopullisesti perille menemättömästä toimituksesta tulee ilmoitus.

Yhdistetyt sovellukset

Tekoälyavustajat ja muut valmiit sovellukset yhdistetään kirjautumalla, ei avainta kopioimalla: sovelluksessa valitaan Kelomo, käyttäjä kirjautuu, valitsee organisaation ja hyväksyy pyydetyt oikeudet. Sovellus toimii hyväksyjän oikeuksilla eikä koskaan saa enempää kuin mitä hänellä itsellään on — jos sovellus pyytää laajempia oikeuksia, hyväksyntänäyttö kertoo sen etukäteen.

Yhteydet näkyvät kohdassa Asetukset → Rajapinta ja webhookit kohdassa Yhdistetyt sovellukset: mikä sovellus, kenen oikeuksilla ja milloin viimeksi käytetty. Omat yhteytesi näet myös omissa asetuksissasi välilehdellä API-avaimet. Katkaise yhteys purkaa sen heti — sovelluksen seuraava kutsu ei enää mene läpi. Salasanan vaihto tai palautus katkaisee kaikki tilisi yhdistetyt sovellukset.

Yhdistetylle sovellukselle ei koskaan anneta oikeutta hallita organisaation asetuksia, laskutusta tai API-avaimia. Jos integraation on tehtävä sellaista, se tarvitsee palveluavaimen, jonka ihminen luo itse.

API-dokumentaatio ja MCP

Kehittäjädokumentaatio on osoitteessa kelomo.fi/developers: autentikointi, tapahtumat, virhekoodit, käyttörajat ja OpenAPI-kuvaus. Samasta paikasta löytyy MCP-ohje ja OAuth-ohje. MCP-yhteys toimii kummallakin tavalla: asiakas kirjautuu (suositus) tai käyttää kelomo_-avainta. Kummassakin tapauksessa tekoälyasiakas toimii tunnisteen oikeuksien rajoissa.

Jos jokin menee pieleen

Avaimen arvo ei ole enää tallessa. Arvoa ei näytetä uudelleen. Vaihda oman avaimen token tai luo uusi avain ja mitätöi vanha.

Palveluavain vastaa virheellä 401. Jos avaimen omistaja on passivoitu, avain lakkaa toimimasta. Osoita avain toiselle jäsenelle painikkeella Vaihda omistaja.

Pyyntö vastaa virheellä 403. Avaimen oikeudet eivät riitä, tai avain on Vain luku. Luo uusi avain tarvittavilla oikeuksilla.

Webhook-toimitus on tilassa “Pysyvästi epäonnistunut”. Tarkista vastaanottimen osoite ja vastaus toimituslokista, korjaa vastaanotin ja paina Lähetä uudelleen.