Auth0 Callback Route

Use the callback integration to exchange authorization codes for tokens without moving the flow into your upstream. The gateway handles the code-to-token

Use the callback integration to exchange authorization codes for tokens without moving the flow into your upstream. The gateway handles the code-to-token exchange with Auth0's token endpoint at the edge. Your upstream receives the final tokens or an error, never the raw authorization code.

Last reviewed: 2026-03-06

When to use this

Use the Auth0 integration guides when your application uses Auth0 as its identity provider and you want the gateway to handle login redirects, callback token exchange, userinfo retrieval, and token refresh at the edge. This keeps Auth0-specific logic out of your backend services.

Key concepts

• The Auth0 authorizer uses JWKS (JSON Web Key Sets) to verify tokens, so you do not need to manage signing secrets manually. Configure either a static jwks object or a jwks_uri that the gateway fetches at startup.

• The callback integration (auth0_callback) exchanges the authorization code for tokens at the edge, so your backend never sees the authorization code or client secret.

• The login redirect integration sends users to Auth0's /authorize endpoint with the correct parameters. The gateway constructs the redirect URL from the authorizer config.

• Refresh token and userinfo routes let you centralize all Auth0 API interactions behind the gateway, giving clients a single domain for auth operations.

• All Auth0 secrets (client_secret, domain) should use $secrets.* or $env.* placeholders so they are resolved from Cloudflare environment variables at startup.

Repo-grounded example

{
  "authorizer": {
    "type": "auth0",
    "domain": "$env.AUTH0_DOMAIN",
    "client_id": "$env.AUTH0_CLIENT_ID",
    "client_secret": "$secrets.AUTH0_CLIENT_SECRET",
    "redirect_uri": "https://api.example.com/api/v1/auth0/callback",
    "callback_uri": "https://app.example.com/auth/callback",
    "jwks_uri": "https://tenant.us.auth0.com/.well-known/jwks.json",
    "scope": "openid profile email"
  },
  "paths": [
    {
      "method": "GET",
      "path": "/api/v1/auth0/callback",
      "integration": { "type": "auth0_callback" }
    }
  ]
}

This snippet defines the callback path at /api/v1/auth0/callback with the auth0_callback integration type. When Auth0 redirects the user here after login, the gateway exchanges the authorization code for tokens using the client credentials in the authorizer config.

Troubleshooting

• If the callback route returns a 500, confirm that redirect_uri in your config exactly matches the callback URL registered in your Auth0 application settings (including scheme and path).

• If JWKS validation fails, check that the jwks_uri is reachable from the Cloudflare edge and returns a valid JWKS JSON document. Test it with curl from your local machine first.

• If the login redirect goes to the wrong Auth0 tenant, verify that domain in the authorizer block points to your correct Auth0 tenant (e.g., your-tenant.us.auth0.com).

• If refresh token exchange returns an error, confirm that the Auth0 application has "Refresh Token Rotation" enabled and that the offline_access scope is included.

Related docs

• auth0

• authorizer

• gateway troubleshooting matrix