# Overview

This guide explains how to configure the Serverless API Gateway with secure practices for different environments.

## 📁 Configuration Files

### Core Configuration Files

* **`src/api-config.json`** – Main API configuration
* **`src/api-config.schema.json`** – JSON schema for validation
* **`wrangler.toml`** – Cloudflare Workers configuration
* **`wrangler.auth.toml`** – Authentication-specific configuration (should be gitignored)
* **`docs/config-examples/*.json`** – Canonical, schema-validated examples used by tests/docs checks

### Environment-Specific Configurations

You can keep separate config files per environment. If you do, validate each one against `src/api-config.schema.json` before deploy.

## 🔧 Configuration Templates

### Basic API Configuration Template

```json
{
  "$schema": "./api-config.schema.json",
  "title": "Your API Title",
  "description": "Description of your API",
  "cors": {
    "allow_origins": ["https://your-domain.com"],
    "allow_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    "allow_headers": ["Content-Type", "Authorization"],
    "expose_headers": ["*"],
    "allow_credentials": true,
    "max_age": 3600
  },
  "paths": [
    {
      "method": "GET",
      "path": "/health",
      "response": { "status": "ok", "version": "1.0.0" }
    },
    {
      "method": "GET",
      "path": "/api/v1/public",
      "response": {
        "message": "This is a public endpoint"
      },
      "auth": false
    }
  ]
}
```

### Supabase Configuration Template

```json
{
  "$schema": "./api-config.schema.json",
  "title": "Supabase API Gateway",
  "description": "API Gateway with Supabase authentication",
  "cors": {
    "allow_origins": ["https://app.example.com"],
    "allow_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    "allow_headers": ["*"],
    "expose_headers": ["*"],
    "allow_credentials": true,
    "max_age": 3600
  },
  "authorizer": {
    "type": "supabase",
    "jwt_secret": "$env.SUPABASE_JWT_SECRET",
    "issuer": "https://YOUR_PROJECT_ID.supabase.co/auth/v1",
    "audience": "authenticated"
  },
  "paths": [
    { "method": "GET", "path": "/health", "response": { "status": "ok" } },
    { "method": "POST", "path": "/api/v1/supabase/auth", "integration": { "type": "supabase_passwordless_auth" } },
    { "method": "POST", "path": "/api/v1/supabase/verify", "integration": { "type": "supabase_passwordless_verify" } },
    {
      "method": "GET",
      "path": "/api/v1/protected",
      "response": {
        "status": "success",
        "message": "This is a protected endpoint"
      },
      "auth": true
    }
  ]
}
```

### Auth0 Configuration Template

```json
{
  "$schema": "./api-config.schema.json",
  "title": "Auth0 API Gateway",
  "description": "API Gateway with Auth0 authentication",
  "cors": {
    "allow_origins": ["https://app.example.com"],
    "allow_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    "allow_headers": ["*"],
    "expose_headers": ["*"],
    "allow_credentials": true,
    "max_age": 3600
  },
  "authorizer": {
    "type": "auth0",
    "domain": "$env.AUTH0_DOMAIN",
    "client_id": "$env.AUTH0_CLIENT_ID",
    "client_secret": "$secrets.AUTH0_CLIENT_SECRET",
    "redirect_uri": "https://your-api.com/api/v1/auth0/callback",
    "callback_uri": "https://your-api.com/api/v1/auth0/callback-redirect",
    "jwks_uri": "https://your-domain.us.auth0.com/.well-known/jwks.json",
    "scope": "openid profile email"
  },
  "paths": [
    { "method": "GET", "path": "/health", "response": { "status": "ok" } },
    { "method": "GET", "path": "/api/v1/auth0/callback", "integration": { "type": "auth0_callback" } },
    { "method": "GET", "path": "/api/v1/auth0/profile", "integration": { "type": "auth0_userinfo" }, "auth": true },
    {
      "method": "GET",
      "path": "/api/v1/protected",
      "response": {
        "status": "success",
        "message": "This is a protected endpoint"
      },
      "auth": true
    }
  ]
}
```

### Wrangler Configuration Template

```toml
# wrangler.toml
name = "your-api-gateway"
main = "src/index.js"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
send_metrics = true
minify = true
workers_dev = false

find_additional_modules = true
rules = [
    { type = "ESModule", globs = ["services/*.js"]}
]

# Environment variables (non-sensitive)
[vars]
ENVIRONMENT = "production"
API_VERSION = "1.0.0"
# Add your non-sensitive environment variables here
# SUPABASE_URL = "https://YOUR_PROJECT_ID.supabase.co"
# AUTH0_DOMAIN = "your-domain.us.auth0.com"
# AUTH0_CLIENT_ID = "your_client_id"

# Secrets are set using: wrangler secret put SECRET_NAME
```

## ✅ Canonical Examples

Use these files as the source of truth for configuration examples:

* `serverlessapigateway/docs/config-examples/minimal.json`
* `serverlessapigateway/docs/config-examples/auth0.json`
* `serverlessapigateway/docs/config-examples/supabase.json`