Blog

OAuth callbacks on localhost: use a reserved tunnel URL

· SyncYak team

  • tunnels
  • oauth
  • local-development

You register http://localhost:3000/callback as a redirect URI, the login flow works, and months later the provider stops accepting it. Or you add a tunnel, register its random address, and the next restart breaks the app because the address changed. Both problems have the same fix: a stable public HTTPS address that forwards to your machine.

Why localhost redirect URIs keep breaking

OAuth providers tighten redirect URI rules over time, and local development is usually the first casualty.

  • Teamwork now rejects localhost addresses (localhost, 127.0.0.1 and ::1) as redirect URIs for dynamically registered apps, and applies the rule at token exchange too. Its sunset notice lists a public HTTPS tunnel as one way to migrate.
  • Spotify removed HTTP redirect URIs and localhost aliases on November 27, 2025, and requires HTTPS redirect URIs.

Policies differ by provider, and some still allow plain HTTP on the literal loopback host. Check your provider's current documentation. The direction is clear, though: the safest redirect URI for development is a real HTTPS address, not localhost.

What a callback needs from a tunnel

A tunnel is a good fit for OAuth because the flow is simple: your browser leaves your app, signs in at the provider, and the provider redirects the browser back to the registered URI. The redirect only has to resolve in the browser that started the flow, but many providers also call your server directly (token exchange, webhooks, app events), and those calls come from the public internet.

For that to work reliably, the address needs three properties:

  1. HTTPS. Most providers require it, and secure cookies and SameSite settings behave the way they will in production.
  2. Stability. The redirect URI is registered in the provider's dashboard. If the address changes on every restart, you edit that setting every time.
  3. Visibility. When a callback fails, you want to see the exact request and response, not guess from a browser error.

Random names versus reserved names

SyncYak Tunnel gives you both kinds of address.

A random address is printed when you start a tunnel:

$ syncyak http 3000
Forwarding https://quiet-yak-4821.syncyak.cloud
        to http://localhost:3000

It is fine for a quick demo or a one-off check. It is the wrong choice for OAuth, because the name is different the next time you run the command.

A reserved subdomain keeps the same name across restarts:

$ syncyak http 3000 myapp.syncyak.live
Forwarding https://myapp.syncyak.live
        to http://localhost:3000

Register https://myapp.syncyak.live/auth/callback once, and it keeps working for as long as you hold the reservation. Reserved subdomains start on the Hobby plan, which is $8 a month and includes 3 reserved subdomains and 3 tunnels. Free includes 1 tunnel with a random subdomain.

Set it up in five steps

  1. Start the tunnel with a reserved name: syncyak http 3000 myapp.syncyak.live.
  2. In your provider's developer dashboard, add https://myapp.syncyak.live/auth/callback as a redirect URI. Keep the path identical to the route in your app, including any trailing slash. Most providers compare the string exactly.
  3. Put the same value in your local environment file, for example OAUTH_REDIRECT_URI. Read it from configuration rather than building it from the incoming request host, so your app and the provider always agree.
  4. Open your app through the public address, not through localhost. Cookies are set per host, so starting the flow on localhost and returning on the tunnel address loses the session and fails the state check.
  5. Sign in. When the provider redirects back, the request shows up in the Tunnel inspector.

A minimal Node example of reading the redirect URI from configuration:

const redirectUri = process.env.OAUTH_REDIRECT_URI;

app.get('/auth/login', (req, res) => {
  const state = crypto.randomUUID();
  res.cookie('oauth_state', state, { httpOnly: true, secure: true, sameSite: 'lax' });
  const params = new URLSearchParams({
    client_id: process.env.OAUTH_CLIENT_ID,
    redirect_uri: redirectUri,
    response_type: 'code',
    state,
  });
  res.redirect(`https://provider.example/authorize?${params}`);
});

Because you are browsing the app on the tunnel address, secure: true works the same way it will in production.

Debugging a callback that fails

Most OAuth callback failures come from a handful of causes, and the inspector helps with each:

  • redirect_uri mismatch. Compare the redirect_uri the provider received with the one registered. A scheme, host, path or trailing slash difference is enough to fail.
  • State mismatch. Check that the cookie set at login arrives on the callback request. If it is missing, the flow probably started on a different host.
  • Proxy headers. If your framework builds absolute URLs from the request, it may produce http:// addresses behind the tunnel. Configure it to trust forwarded headers or, better, use the fixed value from step 3.
  • Server-to-server calls. Some providers send events or token requests straight to your server. The inspector shows those requests with their bodies, so you can replay your handler without repeating the whole sign-in.

The inspector keeps each request and response for your plan's window: 24 hours on Free, 72 hours on Hobby, 168 hours on Pro.

Keep it safe

A public address is public. Do not leave a tunnel running against a development database with real user data. Use test accounts at the provider, keep client secrets in environment variables, and stop the tunnel with Ctrl+C when you finish. The tunnel safety checklist covers access controls in more detail.

How SyncYak helps

SyncYak Tunnel puts a local port on a public HTTPS address with one command, keeps your address across restarts with a reserved subdomain, and records each request in the inspector. If you are weighing it against other tools, the ngrok alternative page compares the approach. Tunnel runs on the same account as the other SyncYak products, so your team has one login and one bill. See the current limits on the pricing page.

Next step

Reserve a subdomain, register the callback once, and stop editing redirect URIs. Create a free SyncYak account and run your first tunnel to see the address before you register it.

Start free with SyncYak · All posts