Authentication

This guide explains how to configure and use authentication with the Serverless API Gateway, supporting both Auth0 and Supabase integrations.

🔐 Supported Authentication Providers

• Auth0 – OAuth 2.0 / OpenID Connect provider

• Supabase – Open-source Firebase alternative with built-in auth

🚀 Quick Start

1. Configuration Setup

Create your src/api-config.json file with one of the authentication providers:

For Supabase:

{
  "$schema": "./api-config.schema.json",
  "title": "Supabase Integration",
  "description": "Configuration for Supabase authentication",
  "cors": {
    "allow_origins": ["*"],
    "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": "protected endpoint",
        "message": "You are successfully authenticated!"
      },
      "auth": true
    }
  ]
}

For Auth0:

{
  "$schema": "./api-config.schema.json",
  "title": "Auth0 Integration",
  "description": "Configuration for Auth0 authentication",
  "cors": {
    "allow_origins": ["*"],
    "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": "$env.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": "protected endpoint",
        "message": "You are successfully authenticated!"
      },
      "auth": true
    }
  ]
}

2. Environment Variables & Secrets

For Supabase:

# Environment Variables (in wrangler.toml)
SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
SUPABASE_KEY=your_anon_key_here

# Secrets (use wrangler secret put)
wrangler secret put SUPABASE_JWT_SECRET

For Auth0:

# Environment Variables (in wrangler.toml)
AUTH0_DOMAIN=your-domain.us.auth0.com
AUTH0_CLIENT_ID=your_client_id_here

# Secrets (use wrangler secret put)
wrangler secret put AUTH0_CLIENT_SECRET
wrangler secret put AUTH0_JWKS

3. Deploy

wrangler deploy

🔍 Authentication Flows

Supabase OTP Flow

1. Send OTP: POST /api/v1/supabase/auth

2. Verify OTP: POST /api/v1/supabase/verify

3. Use Token: Include Bearer YOUR_ACCESS_TOKEN in the Authorization header

Auth0 OAuth Flow

1. Authorization URL: Direct users to Auth0 login

2. Callback: Auth0 redirects to your callback URL with authorization code

3. Token Exchange: Callback endpoint exchanges code for tokens automatically

4. Use Token: Include the ID token in the Authorization header

🛡️ Security Best Practices

• Keep JWT secrets secure by storing them as Wrangler secrets

• Use HTTPS for all callback URLs

• Rotate credentials regularly

For additional Supabase OTP tips, see the Supabase OTP Configuration Guide.