How to Handle Refresh Tokens at the Edge

The short answer: The edge tier should own the transport mechanics of refresh flows only when that reduces client and backend complexity without hiding session-state responsibilities from the application.

When to read this

• You already use Auth0 refresh behavior through the gateway.
• You want a clearer contract for token renewal.
• You need to explain where session responsibility actually lives.

What matters in practice

• Refresh endpoints should be explicit and isolated.
• Do not blur the line between token exchange and application session design.
• Document error handling and required headers up front.

Concrete example

        {
        "authorizer": {
          "type": "auth0",
          "domain": "$env.AUTH0_DOMAIN",
          "client_id": "$env.AUTH0_CLIENT_ID",
          "client_secret": "$secret.AUTH0_CLIENT_SECRET",
          "redirect_uri": "https://serverlessapigateway.com/api/auth0/callback",
          "jwks_uri": "https://tenant.auth0.com/.well-known/jwks.json",
          "scope": "openid profile email"
        },
        "paths": [
          { "method": "GET", "path": "/api/auth0/callback", "integration": { "type": "auth0_callback" } },
          { "method": "GET", "path": "/api/auth0/profile", "auth": true, "integration": { "type": "auth0_userinfo" } },
          { "method": "GET", "path": "/api/auth0/refresh", "integration": { "type": "auth0_refresh" } }
        ]
      }

The example above is intentionally small because the best gateway configs stay readable. Add only the route, auth, and mapping behavior you actually need.

How this maps to the current gateway

The current codebase already supports the behavior discussed here through its config schema, route matcher, and integration handlers. That is why this project is a good fit for reader-first examples: the docs and blog can point to real, implemented behavior instead of hypothetical gateway features.

What this product does not do

• The repo handles refresh transport, not your full session UX.
• Secure token storage and browser strategy are still application concerns.

FAQ

Should the frontend call Auth0 directly or the gateway?

Either can work, but the gateway route centralizes the server-facing token exchange.

What is the main operational risk?

Treating refresh-token exchange as the whole auth strategy instead of one step in it.

Related docs

• auth0 refresh token route
• auth0 on cloudflare workers what to document before you ship
• edge auth patterns for spa backends

Last reviewed: March 6, 2026