BrewForge Docs

Authentication

How to authenticate with the BrewForge API using a Bearer API token or an OAuth access token, the scopes and error responses

All API requests require authentication using a Bearer token.

Creating an API Token

  1. Log in to BrewForge
  2. Go to Settings → Integrations → API tokens
  3. Click Create token
  4. Under Name, say where it is used (e.g. "Home Assistant")
  5. Under Can access, tick the scopes you need (see Token Scopes)
  6. Click Create token
  7. Copy your token from Copy your token: it is shown only this once

Your token looks like bfk_ followed by 32 characters, for example bfk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6.

The API tokens page explains the screen, editing scopes, regenerating and deleting tokens.

Using Your Token

Include the token in the Authorization header:

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

JavaScript Example

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

Token Scopes

Tokens are scoped to areas of your data. Request only the scopes you need. Each area has a :read scope to look things up and a :write scope to create, change and delete; write does not include read, so tick both when a program needs both.

ScopeAllows
readRead everything, in every area below
writeCreate, change and delete everything, in every area below
brews:read / brews:writeBrews and recipes with notes, fermentation readings, brew day measurements, ratings and evaluations, devices, the calendar and a brew's custom field values
inventory:read / inventory:writeIngredient stock, the ingredient catalog and custom ingredients, packages, orders and the planner
cellar:read / cellar:writeCellar vessels and stays, packaging, packaged stock (kegs, bottles), tap lists, labels and TRMNL screens
profiles:read / profiles:writeProfiles: mash, fermentation and water (REST), and in the actions API also equipment profiles and hopstand curves
equipment:read / equipment:writeEquipment profiles in the REST API
styles:read / styles:writeStyle profiles
custom-fields:read / custom-fields:writeCustom field definitions
settings:read / settings:writePreferences (units, defaults), imports and their undo, data export, calculators
community:read / community:writeCommunity, brewer profiles, feedback threads and posts, support tickets, inbox, changelog and account overview

Each endpoint in the API reference and each tool in the tool reference names the scope it needs. The list is also published machine-readably at https://brewforge.sh/.well-known/oauth-protected-resource.

OAuth access tokens

Apps you connect through the MCP server (Claude, ChatGPT, Cursor, …) don't use API tokens. They sign you in with OAuth 2.1 and get access tokens that start with bfo_, last one hour and are renewed with a refresh token. An OAuth app has read or write (which then includes reading), never single areas. You see and disconnect these apps under Settings → Integrations → API tokens → Connected apps. OAuth access tokens work for the actions API and the MCP server.

Error Responses

401 Unauthorized

The token is missing, malformed, unknown or expired. The message says which:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API token"
  }
}
MessageCause
Missing Authorization headerNo Authorization: Bearer … header
Invalid token formatThe token doesn't start with bfk_ or isn't 36 characters long

On the actions API and the MCP server the messages differ slightly, and the 401 response carries a WWW-Authenticate header that tells OAuth clients where to sign in. | Invalid API token | No such token (deleted, regenerated or mistyped) | | API token has expired | The token's expiry date has passed |

403 Forbidden

Token lacks required scope:

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

Add the scope to the token in Settings → Integrations → API tokens. The token value stays the same. The actions API names it in details.required_scope.

Subscription Requirements

API access requires a Pro, AI, or Commercial plan. Requests from Free and Basic accounts receive a 403:

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

Token Security

  • Tokens are never stored in plain text. BrewForge stores only a SHA-256 hash.
  • If you lose your token, you cannot retrieve it: regenerate it (or create a new one) instead.
  • Tokens created in the app don't expire (the list shows No expiry). Delete or regenerate a token when you no longer need it.
  • Each token tracks its last used time, visible in Settings → Integrations → API tokens.

Security Best Practices

  • Never commit tokens to version control
  • Use environment variables to store tokens
  • Use one token per app or script, so you can revoke one without breaking the others
  • Rotate tokens regularly: regenerate or delete old tokens in Settings → Integrations → API tokens
  • Use minimal scopes: only request what you need

On this page