# Auth0

Integrate [Auth0](https://auth0.com) with the [Serverless API Gateway](/getting-started/introduction.md) to add OAuth 2.0 / OpenID Connect authentication to your API. This page covers the required configuration parameters, environment variables, path setup, and the authorization flow.

For general authentication concepts and comparison with other providers, see the [Authentication Guide](/configuration/authentication.md). For JWT-based authorization without a third-party provider, see [Authorizer](/configuration/authorizer.md).

## Prerequisites

Before configuring the Serverless API Gateway, create an Auth0 application:

1. Log in to your [Auth0 Dashboard](https://manage.auth0.com/)
2. Go to **Applications** and click **Create Application**
3. Choose **Regular Web Application** or **Single Page Application** depending on your use case
4. Note the **Domain**, **Client ID**, and **Client Secret** from the application settings
5. Under **Allowed Callback URLs**, add your gateway callback URL (e.g. `https://your-api-url/api/v1/auth0/callback`)

## Configuration Parameters

```json
{
    "authorizer": {
        "type": "auth0",
        "domain": "your-auth0-domain.auth0.com",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "redirect_uri": "https://your-api-url/api/v1/auth0/callback",
        "jwks": "{JSON Escaped JWKS}",
        "jwks_uri": "https://your-auth0-domain.auth0.com/.well-known/jwks.json",
        "scope": "openid profile email"
    }
}
```

### Parameters Explained

* **type**: Specifies the type of authorizer being used. In this case, it is set to "auth0".
* **domain**: The Auth0 domain associated with your account. Replace `your-auth0-domain` with your actual Auth0 domain.
* **client\_id**: The unique identifier for your Auth0 application. Found in the Auth0 Dashboard under **Applications** > your app > **Settings**. Replace `your-client-id` with your actual client ID.
* **client\_secret**: The secret key associated with your Auth0 application. This value should be stored as a Wrangler secret, not in plain text. Replace `your-client-secret` with your actual client secret.
* **redirect\_uri**: The URI to which Auth0 will redirect users after authentication. This must match one of the **Allowed Callback URLs** in your Auth0 application settings.
* **jwks**: A JSON Web Key Set (JWKS) containing the public keys used to verify the JWT signatures. Replace the values in the `n`, `kid`, `x5t`, and `x5c` fields with your actual key values. Either `jwks` or `jwks_uri` is required.
* **jwks\_uri**: The URI to retrieve the JWKS from Auth0. Replace `your-auth0-domain` with your actual Auth0 domain. Either `jwks` or `jwks_uri` is required.
* **scope**: The permissions being requested from the user. Common scopes include `openid`, `profile`, and `email`.

## Environment Variables and Secrets

Store sensitive Auth0 credentials securely:

```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 the authorizer config
wrangler secret put AUTH0_JWKS
```

Reference these in your `api-config.json` using the `$env.` and `$secrets.` prefixes:

```json
{
    "authorizer": {
        "type": "auth0",
        "domain": "$env.AUTH0_DOMAIN",
        "client_id": "$env.AUTH0_CLIENT_ID",
        "client_secret": "$secrets.AUTH0_CLIENT_SECRET",
        "redirect_uri": "https://your-api-url/api/v1/auth0/callback",
        "jwks_uri": "https://your-domain.us.auth0.com/.well-known/jwks.json",
        "scope": "openid profile email"
    }
}
```

### Important Notes

* Ensure that sensitive information such as `client_secret` is stored securely using `wrangler secret put` and not exposed in public repositories or logs.
* Update the placeholders in the configuration with your actual Auth0 account details before deployment.
* Test the configuration in a safe environment before moving to production.

## Path Configurations

This section outlines the path configuration for handling the Auth0 OAuth flow. Add these paths to the `paths` array in your `api-config.json`.

### Callback Handler

```json
{
    "method": "GET",
    "path": "/api/v1/auth0/callback",
    "integration": {
        "type": "auth0_callback"
    }
}
```

This integration handles the callback from Auth0, receiving an authorization code. It exchanges this code for access and ID tokens and returns them to the client.

### Login Redirect

```json
{
    "method": "GET",
    "path": "/api/v1/auth0/callback-redirect",
    "integration": {
        "type": "auth0_callback_redirect"
    },
    "auth": false
}
```

This integration facilitates the redirection to the Auth0 login page (`/authorize`), allowing users to authenticate via Auth0. It provides a seamless way to initiate the login process based on the Auth0 configuration.

### User Info

```json
{
    "method": "GET",
    "path": "/api/v1/auth0/profile",
    "integration": {
        "type": "auth0_userinfo"
    },
    "auth": true
}
```

This integration retrieves user information from Auth0 using the `/userinfo` endpoint. It allows applications to access user profile data after successful authentication.

## Auth0 OAuth Flow

The complete authorization flow with Serverless API Gateway and Auth0 works as follows:

1. **Initiate Login** -- Direct the user to your `/api/v1/auth0/callback-redirect` endpoint. This redirects them to the Auth0 login page.
2. **User Authenticates** -- The user logs in through Auth0 (username/password, social login, etc.).
3. **Callback** -- Auth0 redirects back to your `/api/v1/auth0/callback` endpoint with an authorization code.
4. **Token Exchange** -- The gateway exchanges the authorization code for access and ID tokens automatically.
5. **Access Protected Routes** -- Use the returned token in the `Authorization: Bearer <token>` header to call endpoints that have `"auth": true`.

## CORS Configuration

If your frontend calls the Auth0 endpoints from a browser, configure [CORS](/configuration/cors.md) in your `api-config.json`:

```json
{
  "cors": {
    "allow_origins": ["https://your-frontend.example.com"],
    "allow_methods": ["GET", "POST", "OPTIONS"],
    "allow_headers": ["Authorization", "Content-Type"],
    "allow_credentials": true,
    "max_age": 3600
  }
}
```

## Related Pages

* [Authentication Guide](/configuration/authentication.md) -- full authentication setup overview
* [Authorizer Configuration](/configuration/authorizer.md) -- JWT and provider-based authorization details
* [CORS Configuration](/configuration/cors.md) -- cross-origin request settings
* [Supabase OTP Integration](/configuration/supabase-otp.md) -- alternative authentication with Supabase
* [Auth0 Quickstart](/reader-guides/quickstart-first-proxy/quickstart-auth0-route.md) -- step-by-step Auth0 quickstart
* [Auth0 Documentation](https://auth0.com/docs) -- official Auth0 docs


---

# 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/auth0.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.