OAuth och AI-gränssnittet (MCP)

På den här sidan berättar vi hur du kan ge externa program — till exempel AI-assistenter — tillstånd att läsa och uppdatera uppgifterna på ditt BrewOS-konto på ett säkert sätt. Anvisningen är avsedd för alla användare och förutsätter inga tidigare tekniska kunskaper. Vi går igenom sakerna i lugn och ro och grundligt.

Kort sagt: vad handlar det om?

BrewOS används oftast i en webbläsare: du loggar in, klickar dig fram i menyerna och tittar på eller redigerar uppgifterna själv. Ibland vore det ändå praktiskt om något annat program kunde göra en del av arbetet åt dig. Exempel:

• Du ber en AI-assistent (som Claude eller motsvarande) att lista vilka produkter som finns i lager, eller att registrera en ny kund — och den gör det åt dig.
• Ett av ditt företags egna system hämtar automatiskt försäljningssiffror från BrewOS.
• Ett automationsverktyg registrerar mätresultat för en produktionssats.

För att detta ska vara möjligt behövs två saker:

1. Ett gränssnitt — en "dörr" genom vilken ett annat program kan kommunicera med BrewOS. Den här dörren finns alltid, och dess tekniska namn är MCP (Model Context Protocol). Du behöver inte veta mer om MCP än så — det är bara ett allmänt sätt för AI-verktyg att ansluta sig till tjänster.
2. Auktorisering — det tillstånd du ger vid dörren genom att logga in och godkänna åtkomsten. Utan auktorisering förblir dörren låst.

Auktoriseringen ges med OAuth-inloggning: verktyget skickar dig till BrewOS inloggningssida, och du godkänner åtkomsten. Du behöver inte kopiera eller förvara någon nyckel för hand. Resten av den här sidan berättar hur anslutningen upprättas och hur du administrerar de åtkomster du har beviljat.

Den viktigaste principen: anslutningen fungerar med dina behörigheter

Det här är anvisningens viktigaste del, så läs den noga.

När du godkänner en applikations åtkomst fungerar applikationen med exakt dina behörigheter — varken mer eller mindre. Den får inget eget separat ID, utan agerar i ditt namn:

• Om du har rätt att se kunderna, ser också applikationens förfrågningar dem.
• Om du inte har rätt till någon del, kommer inte heller applikationen dit.
• Åtkomsten är alltid bunden till ett konto (företag). Den kommer inte åt andra kontons uppgifter, även om du har behörigheter till flera konton.

Behörigheterna kontrolleras på nytt varje gång. Om din roll ändras får applikationen genast behörigheter enligt din nya roll. Om du tas bort från kontot slutar alla åtkomster du har beviljat för det kontot att fungera omedelbart. Applikationen kan alltså aldrig göra mer än du själv kan göra just nu.

Behörighetsnivåer

När du godkänner åtkomsten väljer du hur mycket makt applikationen får. Alternativen är:

• Endast läsa — applikationen kan bara titta på uppgifter (t.ex. lista produkter eller kunder). Den kan inte ändra något. Det här är det säkraste alternativet, och det lönar sig att använda det alltid när det räcker med att läsa uppgifter.
• Läsa och skriva — applikationen kan både titta på och redigera uppgifter: skapa kunder, bokföra betalningar, starta produktionssatser och så vidare. Ge den här nivån bara till verktyg som du litar på.

Även om du väljer "Läsa och skriva" är åtkomsten ändå begränsad till dina egna behörigheter och till det valda kontot — valet av nivå kan bara begränsa behörigheterna, aldrig utvidga dem.

Så här ansluter du ett verktyg

De flesta moderna AI-verktyg har inbyggt stöd för OAuth. Gör så här:

1. Lägg till en ny anslutning (connector / MCP-server) i verktyget och ange bara gränssnittets adress:

   https://brewos.fi/mcp
   

   Den exakta adressen ser du också på sidan Inställningar > AI-agenter under Ansluta en agent. Den är alltid /mcp tillagt efter din BrewOS-adress.

2. Verktyget öppnar ett inloggningsfönster för BrewOS. Logga in som vanligt (e-post, lösenord och vid behov en OTP-kod).

3. På godkännandesidan väljer du under Konto det konto som du ger åtkomst till och under Behörighetsnivå antingen Läsa och skriva (standard) eller Endast läsa. Tryck till sist på Tillåt åtkomst. Knappen Avbryt avbryter anslutningen.
4. Verktyget återvänder automatiskt och är genast klart att användas. Du behöver inte kopiera någon nyckel, och verktyget förnyar åtkomsten automatiskt i bakgrunden.

En beviljad åtkomst gäller i högst 60 dagar. Därefter ber verktyget dig att logga in och godkänna åtkomsten på nytt.

Efter det kan du be verktyget till exempel: "Lista de aktiva produkterna på mitt BrewOS-konto" eller "Lägg till en ny kund som heter Esimerkki Oy", och det kan sköta förfrågan via gränssnittet.

För tekniska användare. OAuth-implementationen följer OAuth 2.1: servern publicerar metadata på adresserna /.well-known/oauth-protected-resource och /.well-known/oauth-authorization-server, stöder dynamisk klientregistrering (/oauth/register), PKCE (S256) samt beviljandena authorizationcode och refreshtoken. Du behöver inte de här detaljerna om ditt verktyg sköter OAuth åt dig.

Vad kan man göra via gränssnittet?

Via gränssnittet finns en uppsättning verktyg som motsvarar BrewOS olika funktioner. Vilka verktyg en applikation kan använda beror på din roll och på den valda behörighetsnivån: en anslutning med Endast läsa ser bara läsverktygen.

I stora drag finns följande:

• Konto och produkter – kontots grunduppgifter, sökning av produkter och deras uppgifter, produktgrupper, skapande och redigering av produkter, multipack samt prissättning.
• EAN-koder – EAN-nummerområden och -koder, kontroll av en kod, reservering av nästa lediga kod och koppling till en produkt.
• Kunder – sökning, skapande och redigering av kunder, leveransplatser, kundgrupper, exportkunder samt skapande av en kund utifrån uppgifterna i Valviras register över tillståndshavare.
• Recept och produktion – recept med steg och ingredienser, start av produktionssatser, statusändringar, kvittering av steg, anteckningar, mätningar och tappning.
• Lager – saldon och händelser i råvaru- och färdigvarulager, mottagning av råvaror, lagerkorrigeringar och inventeringar, överföringar av färdiga produkter och råvaror mellan lager.
• Leveranser – skapande av leveranser, produktrader, plockning, markering som levererad, annullering och leveransdokument.
• Fakturering och betalningar – skapande av fakturor utifrån en leverans eller separat, fakturarader, aktivering av en faktura, kreditnotor samt bokföring och allokering av betalningar.
• Rapporter – bl.a. försäljnings-, leverans-, faktura-, betalnings-, produktions- och lagerrapporter, kundfordringar, sammandragsdeklaration för EU-försäljning, Valvira-rapporter och spårbarhet för partier.
• EMCS – sändning av elektroniska administrativa dokument (e-AD) för exportleveranser, kontroll av status, registrering av mottagning och annullering.
• Tankar – tankarnas uppgifter och skick, reservationer och flyttning av en sats till en tank.
• Skatter och myndighetsanmälningar – skattehändelser och korrigering av dem, produkternas punktskatteuppgifter samt kontroll av brister i Valvira-anmälningarna.
• Händelselogg – läsning av kontots händelser.

En del verktyg vidtar åtgärder som har följder utanför BrewOS eller som inte kan ångras direkt. EMCS-verktyget skickar till exempel det administrativa dokumentet till Skatteförvaltningen när Skatteförvaltningens EMCS-gränssnitt används. Att markera en leverans som levererad skapar skattehändelser och förbrukar licensliter, och en aktiverad faktura kan bara korrigeras med en kreditnota. Kontrollera alltid vad AI-assistenten tänker göra innan du godkänner en sådan åtgärd.

Verktyget kan självt fråga gränssnittet vilka funktioner det har tillgång till, så du behöver inte lära dig listan utantill. Du kan bara berätta för verktyget vad du vill göra. Gränssnittet ger också AI-assistenten färdiga anvisningar för de vanligaste uppgifterna i flera steg, som att leverera en leverans, skicka en faktura, lagerändringar, tappning, EMCS- och myndighetsanmälningar samt att lägga upp en kund.

Försäljningsanvändare. En försäljningsanvändares anslutning har bara en begränsad uppsättning verktyg: kontots grunduppgifter, uppgifter om produkter och produktgrupper samt lagerförteckningen. Verktygen för kunder, leveranser, fakturering, prissättning och produktion (också produktionssatsernas anteckningar) är inte tillgängliga för försäljningsanvändare.

Administrera anslutna applikationer

Avsnittet Anslutna AI-agenter på sidan Inställningar > AI-agenter listar de applikationer som du har beviljat åtkomst på det här kontot. För var och en ser du:

• AI-agent eller program – applikationens namn
• Rättigheter – Endast läsa eller Läsa och skriva
• Senast använd – när anslutningen senast användes
• Giltig till – när applikationens nuvarande åtkomst går ut. Verktyget förnyar åtkomsten automatiskt i bakgrunden tills den maximala tiden på 60 dagar har gått.

Du kan återkalla vilken åtkomst som helst med knappen återkalla i slutet av raden och genom att bekräfta återkallelsen. Applikationen förlorar åtkomsten omedelbart. Det är nyttigt till exempel när du slutar använda ett verktyg eller misstänker att det inte längre är pålitligt.

Varje användare ser och administrerar bara de åtkomster hon eller han själv har beviljat. Inte heller ägaren ser eller kan återkalla åtkomster som andra användare har beviljat. Om en användare tas bort från kontot slutar alla åtkomster hon eller han har beviljat för det kontot att fungera.

Öppna sidan. Menyn Inställningar syns bara för kontots ägare. Ägaren öppnar sidan genom att välja inställningar och fliken AI-agenter. Andra användare ser ingen länk till sidan i menyn, men kan öppna den direkt från webbläsarens adressfält: lägg till /asetukset/ai_agentit efter kontonumret i kontots adress, till exempel https://brewos.fi/123/asetukset/ai_agentit, där 123 är ditt kontonummer. Kontonumret (id) ser du på sidan Konton, som du öppnar med länken konton i det övre fältet. Också en försäljningsanvändare kan öppna sidan på det här sättet.

Säkerhet

Några viktiga saker som håller ditt konto säkert:

• Använd den lägsta behörighetsnivå som räcker. Om verktyget bara behöver läsa uppgifter, välj Endast läsa.
• Godkänn åtkomst bara för verktyg som du känner igen. Kontrollera alltid på godkännandesidan vilken applikation som begär åtkomst.
• Återkalla åtkomsten genast när verktyget inte längre används.
• Ändringar som görs via gränssnittet registreras i kontots händelselogg i ditt namn, med samma ord som motsvarande ändring på BrewOS-sidorna och med anteckningen (MCP) i slutet av raden, till exempel Kopplade EAN-koden … till produkten … (MCP). Anteckningen visas också i den ändrade produktens, leveransens, fakturans osv. egen händelselogg, så att du i efterhand kan kontrollera vad anslutningarna har ändrat. I loggen registreras bara lyckade anrop som ändrar uppgifter; enbart läsning av uppgifter, misslyckade anrop och anrop som inte ändrade något registreras inte.
• Användningen är begränsad (högst 120 förfrågningar per minut och anslutning), vilket förhindrar överbelastning av misstag eller med avsikt. Vid normal användning når du inte gränsen.

Vanliga frågor

Behöver jag tekniska kunskaper? Nej. Du ger verktyget gränssnittets adress, loggar in och godkänner åtkomsten — resten sköts automatiskt.

Måste jag kopiera eller förvara någon nyckel? Nej. Verktyget hämtar och förnyar åtkomsten själv via OAuth.

Kan applikationen se uppgifterna för mina andra företag? Nej. Varje åtkomst är bunden till ett konto. Om du behöver gränssnittet för flera konton, godkänn åtkomsten separat för varje konto.

Kan applikationen göra mer än jag? Aldrig. Den fungerar med dina behörigheter, och behörigheterna kontrolleras vid varje anrop.

Mitt verktyg har inte stöd för OAuth. Vad gör jag? Kontakta supporten. Det går inte längre att ansluta till AI-gränssnittet med fasta API-nycklar.

Hur är det med vår egen webbutik? En webbutik använder inte AI-gränssnittet utan ett eget webbutiks-API. Kontots ägare skapar en API-nyckel för webbutiken på sidan Inställningar > Webbutiker: nyckeln visas bara en gång, och den kan återkallas på samma sida. För den som bygger webbutiken finns en separat utvecklarguide, och du kan skicka länken direkt till hen.

Hur kopplar jag bort anslutningen? Öppna sidan Inställningar > AI-agenter (se ovan), leta upp applikationen i listan och tryck på återkalla.

---

Den här anvisningen hör till sidan Inställningar > AI-agenter. Läs också Konton och användare, Datasäkerhet och Händelselogg.