Local Development

You can run the OAuth flow end-to-end against localhost while you build your integration. The trick is knowing which Better i18n host to point at — pick the wrong one and the popup lands on a 404 page.

Two prod hosts, two dev hosts

In production both hosts route to the same Cloudflare Worker, so a single base URL works for everything. In local development the dashboard runs in Vite (port 5173) and the API runs in Wrangler (port 52490) as two separate processes — but the dashboard's Vite dev server proxies /api/* to the API. That makes http://localhost:5173 the right base URL for everything during dev.

Configure your integration

# Point at the dashboard host. Vite proxies /api/* to the API for you.
BETTER_I18N_BASE_URL=http://localhost:5173

# Your credentials from partner onboarding (see Register Your App)
BETTER_I18N_CLIENT_ID=...
BETTER_I18N_CLIENT_SECRET=...

const BASE_URL = process.env.BETTER_I18N_BASE_URL ?? "https://dash.better-i18n.com";

const authorizeUrl = `${BASE_URL}/api/auth/mcp/authorize?...`;
const tokenUrl     = `${BASE_URL}/api/auth/mcp/token`;
const meUrl        = `${BASE_URL}/api/oauth-client/me`;
const mintUrl      = `${BASE_URL}/api/oauth-client/installations/${grantId}/tokens`;

The same BASE_URL works for popup redirects (must be a host the user's browser can reach) and for server-to-server fetches (proxied through Vite to the API).

Register dev redirect URIs

Tell us your dev callback URL during partner onboarding. Common patterns:

http://localhost:3000/oauth/callback     # Most server-side frameworks
http://localhost:5173/oauth/callback     # Vite + same-origin SPA
http://localhost:5174/oauth/callback     # Vite SPA on a non-default port

We add them to your application's redirect_urls list. The redirect_uri you pass at authorize time must byte-for-byte match one of the registered entries — protocol, host, port, path. A trailing slash counts.

Common dev pitfalls

"404 Not Found" on localhost:52490/login

Your BETTER_I18N_BASE_URL is pointing at the API host (52490) instead of the dashboard host (5173). The popup tries to render /login but the API has no such route. Switch to http://localhost:5173.

"Invalid redirect URI"

Your dev callback URL isn't on the registered redirect_urls list, or it doesn't byte-for-byte match (e.g. registered http://localhost:3000/oauth/callback but sent http://localhost:3000/oauth/callback/). Ping us with the exact URL you're sending.

"Authorization link expired"

The user took longer than 10 minutes between authorize and consent, or your local dev server restarted between popup open and exchange (PKCE state in localStorage survives, but better-auth's verification record may have expired). Click "Connect" again to get a fresh code.

Popup keeps reloading the dashboard host

You probably ran the OAuth flow once, hit a quick error, and then the second click reuses a stale code_verifier from localStorage. Clear the storage:

Object.keys(localStorage)
  .filter(k => k.includes("pkce") || k.includes("oauth"))
  .forEach(k => localStorage.removeItem(k));

Then try again.

Hitting the API directly (not through the dashboard)

If you're testing token exchange or /me from a server-side script, you can hit the API host directly. Both routes work in production; the dashboard host is only required for browser-facing redirects.

# Both work in production:
curl https://api.better-i18n.com/api/auth/mcp/token   ...
curl https://dash.better-i18n.com/api/auth/mcp/token  ...

# Locally only the dashboard host works (52490 is for direct curl):
curl http://localhost:52490/api/auth/mcp/token        ...   # OK from server
curl http://localhost:5173/api/auth/mcp/token         ...   # OK (Vite proxies)

For browser-initiated requests stick with the dashboard host so PKCE and the consent flow stay on a single origin.

Next step

Once your local flow works, the same code paths work in production with a single env-var swap. See the authorization flow for the full request reference.