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 oikeutesi muuttuvat tai sinut poistetaan tililtä, kaikki 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.

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 näkee, riippuu sinun oikeuksistasi ja valitusta oikeustasosta. Pääpiirteissään tarjolla on:

Tietojen katselu (luku):

• Tilin perustiedot, tuotteet ja varastot
• Asiakkaat ja asiakkaiden haku
• Reseptit ja tuotantoerät

Tietojen muokkaus (luku ja kirjoitus):

• Asiakkaiden luonti ja tietojen päivitys
• Tuotteiden ja ainesosien hinnoittelu
• Toimitusten luonti ja kuvausten muokkaus
• Asiakassuoritusten (maksujen) kirjaaminen
• Ainesosien varastokirjaukset ja varastosiirrot
• Tuotantoerän käynnistäminen, muistiinpanot, mittaukset ja astiointi

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ä.

Huomioita rajauksista. Myynti-roolin käyttäjille asiakas-, toimitus-, laskutus- ja hinnoittelutyökalut eivät toistaiseksi ole käytettävissä rajapinnan kautta; myyntikäyttäjä näkee kuitenkin esimerkiksi tuotetiedot. Lisäksi valmisteiden (lopputuotteiden) varastosiirrot ja -poistot eivät vielä ole mukana rajapinnassa, koska niihin liittyy verokirjauksia, jotka halutaan toteuttaa erikseen huolella.

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.

Sivu on kaikkien tilin käyttäjien käytettävissä, ja jokainen näkee ja hallitsee vain omia myöntämiään pääsyjä.

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ä.
• Kaikki rajapinnan kautta tehdyt toimet kirjautuvat tilin tapahtumalogiin, joten voit jälkikäteen tarkistaa, mitä yhteyksillä on tehty.
• 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? Mene Asetukset → Rajapinta, etsi sovellus listasta ja paina peru.

---

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