BrewForge Docs

Authentifizierung

So meldest du dich mit einem Bearer-API-Token oder einem OAuth-Zugriffstoken an der BrewForge-API an, mit Berechtigungen und Fehlerantworten

Jede API-Anfrage braucht ein Bearer-Token.

Ein API-Token erstellen

  1. Melde dich bei BrewForge an
  2. Öffne Einstellungen → Integrationen → API-Token
  3. Klicke auf Token erstellen
  4. Gib unter Name an, wo es verwendet wird (z. B. „Home Assistant“)
  5. Hake unter Darf zugreifen auf die Berechtigungen an, die du brauchst (siehe Token-Berechtigungen)
  6. Klicke auf Token erstellen
  7. Kopiere dein Token aus Kopiere dein Token: Es wird nur dieses eine Mal angezeigt

Ein Token besteht aus bfk_ und 32 weiteren Zeichen, zum Beispiel bfk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6.

Die Seite API-Token erklärt die Ansicht, das Ändern von Berechtigungen und das Neu-Erzeugen und Löschen von Token.

Das Token verwenden

Schicke das Token im Header Authorization mit:

curl https://brewforge.sh/api/v1/brews \
  -H "Authorization: Bearer bfk_your_token_here"

Beispiel in JavaScript

const response = await fetch('https://brewforge.sh/api/v1/brews', {
  headers: {
    'Authorization': 'Bearer bfk_your_token_here'
  }
});
const brews = await response.json();

Token-Berechtigungen

Ein Token darf nur auf bestimmte Bereiche deiner Daten zugreifen. Gib ihm nur die Berechtigungen, die es braucht. Jeder Bereich hat eine :read-Berechtigung zum Nachschlagen und eine :write-Berechtigung zum Anlegen, Ändern und Löschen; write enthält read nicht, hake also beide an, wenn ein Programm beides braucht.

BerechtigungErlaubt
readAlles lesen, in allen Bereichen unten
writeAlles anlegen, ändern und löschen, in allen Bereichen unten
brews:read / brews:writeSude und Rezepte mit Notizen, Gärmessungen, Brautag-Messungen, Bewertungen, Geräten, dem Kalender und den Werten eigener Felder eines Suds
inventory:read / inventory:writeZutatenbestand, Zutatenkatalog und eigene Zutaten, Pakete, Bestellungen und der Planer
cellar:read / cellar:writeKellerbehälter und Belegungen, Abfüllung, abgefüllter Vorrat (Fässer, Flaschen), Taplisten, Etiketten und TRMNL-Screens
profiles:read / profiles:writeProfile: Maisch-, Gär- und Wasserprofile (REST), in der Actions-API auch Anlagenprofile und Hopstand-Kurven
equipment:read / equipment:writeAnlagenprofile in der REST-API
styles:read / styles:writeBierstilprofile
custom-fields:read / custom-fields:writeDefinitionen eigener Felder
settings:read / settings:writeEinstellungen (Einheiten, Vorgaben), Importe und ihr Rückgängigmachen, Datenexport, Rechner
community:read / community:writeCommunity, Brauerprofile, Feedback-Threads und -Beiträge, Support-Tickets, Posteingang, Changelog und Kontoübersicht

Jeder Endpunkt in der API-Referenz (auf Englisch) und jedes Tool in der Tool-Referenz nennt die Berechtigung, die es braucht. Maschinenlesbar steht die Liste auch unter https://brewforge.sh/.well-known/oauth-protected-resource.

OAuth-Zugriffstoken

Apps, die du über den MCP-Server verbindest (Claude, ChatGPT, Cursor, …), nutzen keine API-Token. Sie melden dich per OAuth 2.1 an und bekommen Zugriffstoken, die mit bfo_ beginnen, eine Stunde gelten und mit einem Refresh-Token erneuert werden. Eine OAuth-App hat read oder write (das dann auch Lesen enthält), nie einzelne Bereiche. Du siehst und trennst diese Apps unter Einstellungen → Integrationen → API-Token → Verbundene Apps. OAuth-Zugriffstoken funktionieren für die Actions-API und den MCP-Server.

Fehlerantworten

Fehlermeldungen der API sind Englisch.

401 Unauthorized

Das Token fehlt, hat das falsche Format, ist unbekannt oder abgelaufen. message sagt, was davon:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API token"
  }
}
MeldungUrsache
Missing Authorization headerKein Header Authorization: Bearer …
Invalid token formatDas Token beginnt nicht mit bfk_ oder ist nicht 36 Zeichen lang

In der Actions-API und beim MCP-Server lauten die Meldungen etwas anders, und die 401-Antwort hat einen WWW-Authenticate-Header, der OAuth-Clients sagt, wo sie sich anmelden. | Invalid API token | Kein solches Token (gelöscht, neu erzeugt oder vertippt) | | API token has expired | Das Ablaufdatum des Tokens ist vorbei |

403 Forbidden

Dem Token fehlt eine Berechtigung:

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "This action requires the 'brews:write' scope",
    "details": {
      "requiredScope": "brews:write"
    }
  }
}

Gib dem Token die Berechtigung unter Einstellungen → Integrationen → API-Token. Der Token-Wert bleibt dabei gleich. Die Actions-API nennt sie in details.required_scope.

Voraussetzung Tarif

Für den API-Zugriff brauchst du den Tarif Pro, AI oder Commercial. Anfragen von Konten im Free- oder Basic-Tarif bekommen 403:

{
  "error": {
    "code": "TIER_REQUIRED",
    "message": "API access requires pro tier or higher",
    "details": {
      "requiredTier": "pro"
    }
  }
}

Sicherheit der Token

  • Token werden nie im Klartext gespeichert. BrewForge speichert nur einen SHA-256-Hash.
  • Wenn du ein Token verlierst, kannst du es nicht wiederherstellen: Erzeuge es neu (oder erstelle ein neues).
  • In der App erstellte Token laufen nicht ab (die Liste zeigt Läuft nicht ab). Lösche oder erzeuge ein Token neu, wenn du es nicht mehr brauchst.
  • Zu jedem Token wird festgehalten, wann es zuletzt benutzt wurde. Du siehst es unter Einstellungen → Integrationen → API-Token.

Empfehlungen

  • Checke Token nie in die Versionsverwaltung ein
  • Speichere Token in Umgebungsvariablen
  • Nimm ein Token pro App oder Skript, dann kannst du eins widerrufen, ohne die anderen zu stören
  • Tausche Token regelmäßig aus: Erzeuge alte Token unter Einstellungen → Integrationen → API-Token neu oder lösche sie
  • Gib nur nötige Berechtigungen: nur das, was das Programm wirklich braucht

Auf dieser Seite