# 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:**

```json
{
  "$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:**

```json
{
  "$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
    }
  ]
}
```

### 2. Environment Variables & Secrets

**For Supabase:**

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

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

### 3. Deploy

```bash
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](https://developers.cloudflare.com/workers/configuration/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

For additional Supabase OTP tips, see the [Supabase OTP Configuration Guide](https://docs.serverlessapigateway.com/configuration/supabase-otp).

For production-ready schema-valid examples, use:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serverlessapigateway.com/configuration/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.