Overview

This document provides detailed guidance on how to use the provided JSON configuration for setting up and managing your application's server, CORS (Cross-Origin Resource Sharing) settings, authorizati

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

{
  "$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

{
  "$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

{
  "$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

# 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