Authentication

All API requests require authentication using a Bearer token.

Creating an API Token

1. Log in to BrewForge
2. Go to Settings → API
3. Click Create Token
4. Give your token a name (e.g., "My Integration")
5. Select the scopes you need:
   • brews:read - Read brew data
   • brews:write - Create, update, delete brews
   • inventory:read - Read inventory
   • inventory:write - Create, update, delete inventory items
   • equipment:read - Read equipment profiles
   • styles:read - Read style profiles
6. Click Create
7. Copy your token immediately - it won't be shown again

Your token will look like: bfk_a1b2c3d4e5f6...

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 specific resources. Request only the scopes you need:

Error Responses

401 Unauthorized

Missing or invalid token:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API token"
  }
}

403 Forbidden

Token lacks required scope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Token missing required scope: brews:write"
  }
}

Subscription Requirements

API access requires a Pro, AI, or Commercial subscription. Requests from Free tier accounts receive a 403 error:

{
  "error": {
    "code": "TIER_REQUIRED",
    "message": "API access requires a Pro subscription or higher"
  }
}

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 — create a new one instead.
• Tokens can have an expiration date. Expired tokens return 401.
• Each token tracks its last used timestamp, visible in Settings → API.

Security Best Practices

• Never commit tokens to version control
• Use environment variables to store tokens
• Rotate tokens regularly - delete old tokens in Settings → API
• Use minimal scopes - only request what you need
• Set expiration dates for tokens you don't need indefinitely