OAuth ja tekoälyrajapinta (MCP)

Tällä sivulla kerrotaan, miten voit antaa ulkopuolisille ohjelmille — esimerkiksi tekoälyavustajille — luvan lukea ja päivittää BrewOS-tilisi tietoja turvallisesti. Ohje on tarkoitettu kaikille käyttäjille, eikä se oleta aiempaa teknistä osaamista. Käymme asiat läpi rauhassa ja perusteellisesti.

Lyhyesti: mistä on kyse?

BrewOS:ää käytetään yleensä selaimella: kirjaudut sisään, klikkailet valikoita ja katselet tai muokkaat tietoja itse. Joskus olisi kuitenkin kätevää, jos jokin toinen ohjelma voisi tehdä osan työstä puolestasi. Esimerkkejä:

• Pyydät tekoälyavustajaa (kuten Claudea tai vastaavaa) listaamaan, mitä tuotteita varastossa on, tai kirjaamaan uuden asiakkaan — ja se tekee sen puolestasi.
• Jokin yrityksesi oma järjestelmä hakee BrewOS:ista automaattisesti myyntiluvut.
• Automaatiotyökalu kirjaa mittaustuloksia tuotantoerään.

Jotta tämä olisi mahdollista, tarvitaan kaksi asiaa:

1. Rajapinta — "ovi", jonka kautta toinen ohjelma voi keskustella BrewOS:in kanssa. Tämä ovi on aina olemassa, ja sen tekninen nimi on MCP (Model Context Protocol). Sinun ei tarvitse tietää MCP:stä sen enempää — se on vain yleinen tapa, jolla tekoälytyökalut osaavat liittyä palveluihin.
2. Valtuutus — lupa, jonka annat ovella kirjautumalla sisään ja hyväksymällä pääsyn. Ilman valtuutusta ovi pysyy lukossa.

Valtuutus annetaan OAuth-kirjautumisella: työkalu ohjaa sinut BrewOS:in kirjautumissivulle, ja sinä hyväksyt pääsyn. Mitään avainta ei tarvitse kopioida tai säilyttää käsin. Tämän sivun loppuosa kertoo, miten yhteys muodostetaan ja miten hallitset myöntämiäsi pääsyjä.

Tärkein periaate: yhteys toimii sinun oikeuksillasi

Tämä on ohjeen tärkein kohta, joten lue se huolella.

Kun hyväksyt sovelluksen pääsyn, sovellus toimii täsmälleen sinun käyttöoikeuksillasi — ei enempää eikä vähempää. Se ei saa omaa erillistä tunnusta, vaan toimii sinun nimissäsi:

• Jos sinulla on oikeus nähdä asiakkaat, myös sovelluksen pyynnöt näkevät ne.
• Jos sinulla ei ole oikeutta johonkin osioon, sovelluskaan ei pääse sinne.
• Pääsy on aina sidottu yhteen tiliin (yritykseen). Se ei pääse käsiksi muiden tilien tietoihin, vaikka sinulla olisi oikeuksia useampaan tiliin.

Oikeudet tarkistetaan joka kerta uudelleen. Jos roolisi muuttuu, sovellus saa heti uuden roolisi mukaiset oikeudet. Jos sinut poistetaan tililtä, kaikki tälle tilille myöntämäsi pääsyt lakkaavat toimimasta välittömästi. Sovellus ei siis voi koskaan tehdä enempää kuin sinä itse pystyt tekemään juuri nyt.

Oikeustasot

Pääsyä hyväksyessäsi valitset, kuinka paljon valtaa sovellukselle annetaan. Vaihtoehdot ovat:

• Vain luku — sovellus voi ainoastaan katsella tietoja (esim. listata tuotteita tai asiakkaita). Se ei voi muuttaa mitään. Tämä on turvallisin vaihtoehto, ja sitä kannattaa käyttää aina, kun pelkkä tietojen lukeminen riittää.
• Luku ja kirjoitus — sovellus voi sekä katsella että muokata tietoja: luoda asiakkaita, kirjata suorituksia, käynnistää tuotantoeriä ja niin edelleen. Anna tämä taso vain työkaluille, joihin luotat.

Vaikka valitset "luku ja kirjoitus", pääsy on silti rajattu sinun omiin oikeuksiisi ja valittuun tiliin — tasovalinta voi vain kaventaa oikeuksia, ei laajentaa niitä.

Näin yhdistät työkalun

Useimmat nykyaikaiset tekoälytyökalut osaavat OAuthin valmiiksi. Toimit näin:

1. Lisää työkaluun uusi yhteys (connector / MCP-palvelin) ja anna sille pelkkä rajapinnan osoite:

   https://brewos.fi/mcp
   

   Tarkan osoitteen näet myös Asetukset > Rajapinta -sivun yläosassa. Se on aina BrewOS-osoitteesi perään lisätty /mcp.

2. Työkalu avaa BrewOS-kirjautumisikkunan. Kirjaudu sisään tavalliseen tapaan (sähköposti, salasana ja tarvittaessa OTP-koodi).

3. Hyväksymissivulla valitse tili, jolle annat pääsyn, sekä oikeustaso (vain luku tai luku ja kirjoitus). Paina lopuksi Salli pääsy.
4. Työkalu palaa automaattisesti takaisin ja on heti käyttövalmis. Mitään avainta ei tarvitse kopioida, ja työkalu uusii pääsyn automaattisesti taustalla.

Myönnetty pääsy on voimassa enintään 60 päivää. Sen jälkeen työkalu pyytää sinua kirjautumaan ja hyväksymään pääsyn uudelleen.

Tämän jälkeen voit pyytää työkalua esimerkiksi: "Listaa BrewOS-tilini aktiiviset tuotteet" tai "Lisää uusi asiakas nimeltä Esimerkki Oy", ja se osaa hoitaa pyynnön rajapinnan kautta.

Teknisille käyttäjille. OAuth-toteutus noudattaa OAuth 2.1:tä: palvelin julkaisee metatiedot osoitteissa /.well-known/oauth-protected-resource ja /.well-known/oauth-authorization-server, tukee dynaamista asiakasrekisteröintiä (/oauth/register), PKCE:tä (S256) sekä authorizationcode- ja refreshtoken-myöntöjä. Et tarvitse näitä yksityiskohtia, jos työkalusi hoitaa OAuthin puolestasi.

Mitä rajapinnan kautta voi tehdä?

Rajapinnan kautta on käytettävissä joukko työkaluja, jotka vastaavat BrewOS:in eri toimintoja. Mitä työkaluja sovellus voi käyttää, riippuu roolistasi ja valitusta oikeustasosta: Vain luku -yhteys näkee vain lukutyökalut.

Pääpiirteissään tarjolla on:

• Tili ja tuotteet – tilin perustiedot, tuotteiden haku ja tiedot, tuoteryhmät, tuotteiden luonti ja muokkaus, monipakkaukset sekä hinnoittelu.
• EAN-koodit – EAN-numeroalueet ja -koodit, koodin tarkistus, seuraavan vapaan koodin varaaminen ja liittäminen tuotteeseen.
• Asiakkaat – asiakkaiden haku, luonti ja muokkaus, toimituspaikat, asiakasryhmät, vientiasiakkaat sekä asiakkaan luonti Valviran luvanhaltijarekisterin tiedoista.
• Reseptit ja tuotanto – reseptit vaiheineen ja ainesosineen, tuotantoerien käynnistys, tilan muutokset, vaiheiden kuittaus, muistiinpanot, mittaukset ja astiointi.
• Varastot – raaka-aine- ja valmistevarastojen saldot ja tapahtumat, raaka-aineiden vastaanotot, varastokorjaukset ja inventaariot, valmisteiden ja raaka-aineiden siirrot varastojen välillä.
• Toimitukset – toimitusten luonti, tuoterivit, poiminta, toimitetuksi merkitseminen, peruminen ja toimitusasiakirjat.
• Laskutus ja suoritukset – laskujen luonti toimituksesta tai erikseen, laskurivit, laskun aktivointi, hyvityslaskut sekä suoritusten kirjaus ja kohdistus.
• Raportit – mm. myynti-, toimitus-, lasku-, suoritus-, tuotanto- ja varastoraportit, myyntisaatavat, EU-myynti-ilmoitus, Valvira-raportit ja erien jäljitettävyys.
• EMCS – vientitoimitusten sähköisten saateasiakirjojen (e-AD) lähetys, tilan tarkistus, vastaanoton kirjaus ja peruutus.
• Tapahtumalogi – tilin tapahtumien lukeminen.

Osa työkaluista tekee toimenpiteitä, joilla on seurauksia BrewOS:in ulkopuolella tai joita ei voi suoraan perua. Esimerkiksi EMCS-työkalu lähettää saateasiakirjan Verohallinnolle, kun Verohallinnon EMCS-rajapinta on käytössä. Toimituksen merkitseminen toimitetuksi muodostaa verotilitapahtumat ja kuluttaa käyttöoikeuslitroja, ja aktivoitua laskua voi korjata vain hyvityslaskulla. Tarkista aina, mitä tekoälyavustaja aikoo tehdä, ennen kuin hyväksyt tällaisen toimenpiteen.

Työkalu osaa itse kysyä rajapinnalta, mitä toimintoja sillä on käytettävissä, joten sinun ei tarvitse opetella luetteloa ulkoa. Voit vain kertoa työkalulle, mitä haluat tehdä.

Myyntikäyttäjät. Myyntikäyttäjän yhteydellä on käytettävissä vain suppea joukko työkaluja: tilin perustiedot, tuotteiden ja tuoteryhmien tiedot sekä varastoluettelo. Asiakas-, toimitus-, laskutus-, hinnoittelu- ja tuotantotyökalut (myös tuotantoerien muistiinpanot) eivät ole myyntikäyttäjän käytettävissä.

Yhdistettyjen sovellusten hallinta

Sivu Asetukset > Rajapinta listaa sovellukset, joille sinä olet myöntänyt pääsyn tällä tilillä. Jokaisesta näet:

• Sovelluksen nimen
• Oikeudet (vain luku / luku ja kirjoitus)
• Milloin yhteyttä on viimeksi käytetty
• Voimassaolon

Voit perua minkä tahansa pääsyn peru-linkistä. Sovellus menettää pääsyn välittömästi. Tämä on hyödyllistä esimerkiksi, kun lopetat jonkin työkalun käytön tai epäilet, ettei se ole enää luotettava.

Jokainen käyttäjä näkee ja hallitsee vain omia myöntämiään pääsyjä. Myöskään omistaja ei näe eikä voi perua muiden käyttäjien myöntämiä pääsyjä. Jos käyttäjä poistetaan tililtä, kaikki hänen tälle tilille myöntämänsä pääsyt lakkaavat toimimasta.

Sivun avaaminen. Asetukset-valikko näkyy vain tilin omistajille. Omistaja avaa sivun valitsemalla asetukset ja välilehden Rajapinta. Muut käyttäjät eivät näe valikossa linkkiä sivulle, mutta voivat avata sen suoraan selaimen osoiteriviltä: lisää tilin osoitteeseen tilinumeron perään /asetukset/api_avaimet, esimerkiksi https://brewos.fi/123/asetukset/api_avaimet, jossa 123 on tilisi numero. Tilinumeron näet esimerkiksi tilit-listasta.

Turvallisuus

Muutama tärkeä asia, joilla pidät tilisi turvassa:

• Käytä pienintä riittävää oikeustasoa. Jos työkalun tarvitsee vain lukea tietoja, valitse Vain luku.
• Hyväksy pääsy vain työkaluille, jotka tunnistat. Tarkista aina hyväksymissivulta, mikä sovellus pääsyä pyytää.
• Peru pääsy heti, kun työkalu ei ole enää käytössä.
• Rajapinnan kautta tehdyt muutokset kirjautuvat tilin tapahtumalogiin muodossa MCP-työkalu: työkalun nimi, joten voit jälkikäteen tarkistaa, mitä yhteyksillä on muutettu. Logiin kirjataan vain onnistuneet, tietoja muuttavat kutsut; pelkkiä tietojen lukuja ei kirjata.
• Käyttöä on rajoitettu (enintään 120 pyyntöä minuutissa yhteyttä kohden), mikä estää vahingossa tai tahallaan tapahtuvan ylikuormituksen. Normaalikäytössä raja ei tule vastaan.

Usein kysyttyä

Tarvitsenko teknistä osaamista? Et. Annat työkalulle rajapinnan osoitteen, kirjaudut sisään ja hyväksyt pääsyn — loput hoituu automaattisesti.

Pitääkö minun kopioida tai säilyttää jotain avainta? Ei. Työkalu hakee ja uusii pääsyn itse OAuthin kautta.

Voiko sovellus nähdä muiden yritysteni tietoja? Ei. Jokainen pääsy on sidottu yhteen tiliin. Jos tarvitset rajapinnan useammalle tilille, hyväksy pääsy erikseen kullekin tilille.

Voiko sovellus tehdä enemmän kuin minä? Ei koskaan. Se toimii sinun oikeuksillasi, ja oikeudet tarkistetaan joka kutsulla.

Työkaluni ei osaa OAuthia. Mitä teen? Ota yhteyttä tukeen. Rajapintaan ei voi enää liittyä kiinteillä API-avaimilla.

Miten katkaisen yhteyden? Avaa Asetukset > Rajapinta -sivu (ks. yllä), etsi sovellus listasta ja paina peru.

---

Tämä ohje liittyy sivuun Asetukset > Rajapinta. Lue myös Tilit ja käyttäjät, Tietoturva ja Tapahtumalogi.