# Authentication

> Securing your API requests to BuildBetter

## Authentication Methods

BuildBetter supports multiple authentication methods:

- API Keys
- OAuth 2.0
- JWT Tokens
- Session Tokens

## API Keys

### Obtaining an API Key

```bash
# 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

```bash
# 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

```http
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

```bash
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

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

### Token Response

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

## JWT Authentication

### JWT Structure

```yaml
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

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

## Session Authentication

### Session Management

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

### Session Endpoints

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

## Security Requirements

### Transport Security

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

### API Security

```yaml
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

- Rotate keys regularly
- Use environment variables
- Limit key exposure
- Monitor key usage

### Token Security

- Short expiration times
- Secure storage
- Regular rotation
- Scope limitation

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

## Error Handling

### Authentication Errors

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

### Common Error Codes

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

## Rate Limiting

### Default Limits

```yaml
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

- SOC 2 Type II
- GDPR compliant
- HIPAA ready
- ISO 27001

### Audit Logging

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

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