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
- Melde dich bei BrewForge an
- Öffne Einstellungen → Integrationen → API-Token
- Klicke auf Token erstellen
- Gib unter Name an, wo es verwendet wird (z. B. „Home Assistant“)
- Hake unter Darf zugreifen auf die Berechtigungen an, die du brauchst (siehe Token-Berechtigungen)
- Klicke auf Token erstellen
- 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.
| Berechtigung | Erlaubt |
|---|---|
read | Alles lesen, in allen Bereichen unten |
write | Alles anlegen, ändern und löschen, in allen Bereichen unten |
brews:read / brews:write | Sude und Rezepte mit Notizen, Gärmessungen, Brautag-Messungen, Bewertungen, Geräten, dem Kalender und den Werten eigener Felder eines Suds |
inventory:read / inventory:write | Zutatenbestand, Zutatenkatalog und eigene Zutaten, Pakete, Bestellungen und der Planer |
cellar:read / cellar:write | Kellerbehälter und Belegungen, Abfüllung, abgefüllter Vorrat (Fässer, Flaschen), Taplisten, Etiketten und TRMNL-Screens |
profiles:read / profiles:write | Profile: Maisch-, Gär- und Wasserprofile (REST), in der Actions-API auch Anlagenprofile und Hopstand-Kurven |
equipment:read / equipment:write | Anlagenprofile in der REST-API |
styles:read / styles:write | Bierstilprofile |
custom-fields:read / custom-fields:write | Definitionen eigener Felder |
settings:read / settings:write | Einstellungen (Einheiten, Vorgaben), Importe und ihr Rückgängigmachen, Datenexport, Rechner |
community:read / community:write | Community, 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"
}
}| Meldung | Ursache |
|---|---|
Missing Authorization header | Kein Header Authorization: Bearer … |
Invalid token format | Das 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
Tools: Community
Alle Tools des Toolsets community im BrewForge-MCP-Server und in der Actions-API, mit Zugriff, Berechtigung, Tariffunktion und Parametern.
Rate-Limits
Limits der BrewForge-API (REST 100 Anfragen pro Stunde und 1.000 pro 30 Tage, Actions-API und MCP 600 pro Stunde und 20.000 pro 30 Tage), Rate-Limit-Header und der Umgang mit 429-Antworten