Auth0: JWKS vs JWKS URI

Choose local JWKS or remote JWKS URI based on whether you want static config or dynamic key retrieval. A local `jwks` object bakes the key set into your config,

Choose local JWKS or remote JWKS URI based on whether you want static config or dynamic key retrieval. A local jwks object bakes the key set into your config, which avoids a network call at startup but requires manual updates when Auth0 rotates keys. A jwks_uri fetches keys dynamically but adds startup latency.

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 uses jwks_uri to point at Auth0's well-known JWKS endpoint. The gateway fetches the key set at startup and uses it to verify token signatures. To use a static JWKS, replace jwks_uri with a jwks field containing the full key set JSON.

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