Authentication

Configure API gateway authentication with JWT, Auth0, and Supabase. Supports OAuth 2.0, OTP passwordless login, and token-based auth.

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

The Serverless API Gateway supports multiple authentication strategies. You can protect any route by setting "auth": true in its path configuration, and the gateway will validate incoming tokens using the configured authorizer.

Supported Authentication Providers

Provider	Type	Use Case
JWT	Token-based (HS256)	Bring your own identity provider; validate tokens with a shared secret. See Authorizer.
Auth0	OAuth 2.0 / OpenID Connect	Managed identity with social logins, MFA, and enterprise connections. See Auth0 Integration.
Supabase	Passwordless OTP	Email OTP, phone OTP, and magic link authentication. See Supabase OTP Integration.

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": ["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": "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": ["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": "protected endpoint",
        "message": "You are successfully authenticated!"
      },
      "auth": true
    }
  ]
}

For JWT (custom provider):

{
  "authorizer": {
    "type": "jwt",
    "secret": "$env.JWT_SECRET",
    "algorithm": "HS256",
    "audience": "your-audience",
    "issuer": "your-issuer"
  },
  "paths": [
    {
      "method": "GET",
      "path": "/api/v1/protected",
      "response": { "status": "protected" },
      "auth": true
    }
  ]
}

See the Authorizer page for all JWT configuration options and supported error codes.

2. Environment Variables and Secrets

For Supabase:

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

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

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
## Optional if you use "jwks" instead of "jwks_uri" in authorizer:
wrangler secret put AUTH0_JWKS

For JWT:

wrangler secret put JWT_SECRET

3. Deploy

wrangler deploy

Authentication Flows

Supabase OTP Flow

1. Send OTP: POST /api/v1/supabase/auth with {"email": "[email protected]"} or {"phone": "[phone]"}

2. Verify OTP: POST /api/v1/supabase/verify with the email/phone and the 6-digit token

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

For detailed configuration, including magic link vs OTP differences and troubleshooting, see the Supabase OTP Configuration Guide. If Supabase sends a magic link instead of a numeric code, start there before debugging the verify endpoint.

Auth0 OAuth Flow

1. Authorization URL: Direct users to Auth0 login via the callback-redirect endpoint

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

For setup steps, required fields, and path configuration, see the Auth0 Integration Guide.

JWT Flow

1. Obtain Token: Generate a JWT from your own identity provider or auth server

2. Include Token: Send it in the Authorization: Bearer <token> header

3. Validation: The gateway validates the signature, audience, and issuer

For JWT configuration details, see Authorizer.

Protecting Routes

Any path can require authentication by adding "auth": true:

{
  "method": "GET",
  "path": "/api/v1/protected-resource",
  "integration": {
    "type": "http_proxy",
    "url": "https://backend.example.com/resource"
  },
  "auth": true
}

When "auth": true is set, the gateway validates the Authorization header using the configured authorizer before forwarding the request. If validation fails, the gateway returns a 401 Unauthorized response.

Security Best Practices

• Keep JWT secrets secure by storing them as Wrangler secrets

• Use HTTPS for all callback URLs

• Rotate credentials regularly

• Send access tokens only in the Authorization: Bearer <token> header

• Send refresh tokens in X-Refresh-Token header or JSON body, never in URL query parameters

• Configure CORS to restrict allowed origins to your frontend domain

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

For production-ready schema-valid examples, use:

• serverlessapigateway/docs/config-examples/auth0.json

• serverlessapigateway/docs/config-examples/supabase.json

Related Pages

• Authorizer Configuration -- JWT validation, error codes, and supported algorithms

• Auth0 Integration -- Auth0-specific setup and OAuth flow

• Supabase OTP Integration -- Supabase email/phone OTP and magic link configuration

• Cost -- estimate how auth work affects your Cloudflare runtime usage

• CORS Configuration -- cross-origin settings for browser-based auth flows

• Integrations Overview -- all available integration types