Auth0 Refresh Token Route

Handle refresh token exchange through the gateway when you want one edge-managed auth surface. The gateway sends the refresh token to Auth0's token endpoint and

Handle refresh token exchange through the gateway when you want one edge-managed auth surface. The gateway sends the refresh token to Auth0's token endpoint and returns the new access token to the client. This keeps the client_secret on the server side and avoids exposing it in frontend 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 configures the Auth0 authorizer with client credentials needed for token refresh. To add a refresh route, create a path with the auth0_refresh_token integration type -- the gateway exchanges the refresh token for a new access token using the stored client secret.

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