BuildBetter Docs

Authentication

Authentication Methods

BuildBetter supports multiple authentication methods:

API Keys

Obtaining an API Key

# Request format
curl -X POST https://api.buildbetter.app/v1/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "expires_in": 31536000,
    "scopes": ["read:calls", "write:signals"]
  }'

Using API Keys

# Example API request with key
curl "https://api.buildbetter.app/v3/rest/recordings?page=1&limit=1" \
  -H "X-BuildBetter-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Warning: Never share or expose your API keys. Rotate them regularly and use environment variables for storage.

OAuth 2.0

Authorization Flow

1. Authorization Request

GET https://auth.buildbetter.app/oauth/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REDIRECT_URI
&scope=read:calls write:signals
&state=random_state_string

2. Token Exchange

curl -X POST https://auth.buildbetter.app/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

3. Use Access Token

curl https://api.buildbetter.app/v1/user \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200641f3e...",
  "scope": "read:calls write:signals"
}

JWT Authentication

JWT Structure

jwt_format:
  header:
    alg: "HS256"
    typ: "JWT"
  
  payload:
    sub: "user_id"
    iss: "buildbetter.app"
    iat: timestamp
    exp: timestamp
    scope: ["read:calls", "write:signals"]

Using JWTs

# Example request with JWT
curl https://api.buildbetter.app/v1/signals \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Session Authentication

Session Management

session_config:
  cookie_name: "bb_session"
  max_age: 86400
  secure: true
  http_only: true
  same_site: "strict"

Session Endpoints

POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
GET /api/v1/auth/session

Security Requirements

Transport Security

security_requirements:
  transport:
    - TLS 1.2 or higher required
    - Valid SSL certificate
    - HSTS enabled
    - Secure cipher suites

API Security

api_security:
  rate_limiting:
    default: "100 requests per minute"
    authenticated: "1000 requests per minute"
    enterprise: "custom limits available"
  
  ip_restrictions:
    whitelist: true
    vpn_support: true
    geo_blocking: available

Best Practices

Key Management

Token Security

Note: Implement the principle of least privilege when requesting API access scopes.

Error Handling

Authentication Errors

{
  "error": "invalid_token",
  "error_description": "The access token has expired",
  "status_code": 401
}

Common Error Codes

error_codes:
  401: "Unauthorized - Invalid credentials"
  403: "Forbidden - Insufficient permissions"
  429: "Too Many Requests - Rate limit exceeded"

Rate Limiting

Default Limits

rate_limits:
  free_tier:
    calls: "100 per minute"
    signals: "500 per minute"
    storage: "1GB per month"
  
  enterprise:
    calls: "unlimited"
    signals: "custom limit"
    storage: "custom quota"

Tip: Monitor your API usage and implement exponential backoff for rate limit handling.

Compliance & Auditing

Security Standards

Audit Logging

audit_events:
  authentication:
    - Login attempts
    - Key creation
    - Token refresh
    - Permission changes

Info: Regular security audits and compliance checks are performed on all authentication systems.