​
Google sign-in — configuration and troubleshooting

Aligned with docs/google-login-setup.md in the main repository (English edition for Mintlify).

​
1. Why do I see 404 Not Found on /api/v1/auth/google?

If visiting http://YOUR_HOST:7860/api/v1/auth/google returns {"detail":"Not Found"}, the running process does not expose /api/v1/* routes. Common causes:
  • Wrong launch mode — The server was not started with the API-enabled Next frontend mode, or the API router failed to load (check startup logs).
  • Split frontend/backend confusion — You opened the “backend URL” directly while Gradio owns / and /api/v1/* is not mounted or is shadowed.
Follow the steps below to fix both “reachable API” and “Google OAuth works”.
For Google sign-in and the Next login page, run one service in Next mode so /api/v1/auth/google is always on that process.

​
2.1 Build the frontend

cd frontend
npm run build
Confirm frontend/out exists (or your configured static export directory).

​
2.2 Start the backend in Next mode (important)

# From the repository root
python biocortex_web_app.py --frontend next --allow-register --port 7860
  • --frontend next — FastAPI serves the API and static Next assets; Gradio does not take over /, so /api/v1/auth/google is reachable.
  • --allow-register — Enables self-registration (including email + admin approval flows).
  • With admin seed users: add e.g. --auth-users "admin:YOUR_PASSWORD" --admin-user admin.
If startup shows:
  • ⚠️ API router failed to load: ...
    then /api/v1 is not mounted; fix dependencies/environment from the error before retrying OAuth.

​
2.3 Environment variables (Google)

Set in the same environment as the process (export before launch or load via .env): 
export GOOGLE_CLIENT_ID="your-client-id"
export GOOGLE_CLIENT_SECRET="your-client-secret"
If unset, Google sign-in typically returns 503 or a JSON “not configured” message, not 404.

​
2.4 Google Cloud Console

  1. Open Google Cloud Console → APIs & Services → Credentials.
  2. Create an OAuth 2.0 Client ID of type Web application.
  3. Authorized redirect URIs must match the URL users actually use, for example:
    • Local: http://localhost:7860/api/v1/auth/google/callback
    • LAN IP: http://10.0.0.5:7860/api/v1/auth/google/callback
    • Production: https://api.biocortex.tech/api/v1/auth/google/callback
  4. Copy Client ID and Client Secret into the variables above.

​
3. Pointing the Next dev server at the backend

If you use Next dev on port 3000 and the API on 7860, set in frontend/.env.local: 
NEXT_PUBLIC_API_URL=http://YOUR_HOST:7860
NEXT_PUBLIC_WS_URL=ws://YOUR_HOST:7860
For HTTPS production sites, use https:// and wss:// for the API host. The “Sign in with Google” link must hit the same host:port where --frontend next is running, or you will still see 404.

​
4. Quick checks

  1. API on the port — Open http://YOUR_HOST:7860/docs. If Swagger loads, confirm GET /api/v1/auth/google exists. If not, the process is not the Next+API mode.
  2. Google flow — Open
    https://YOUR_API_HOST/api/v1/auth/google?return_url=/chat
    • 302 to Google — Route and GOOGLE_CLIENT_ID look good; verify redirect URI in Console matches exactly.
    • 404 — /api/v1 not mounted; restart with --frontend next.
    • 503 / JSON error — Missing or wrong GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET.

​
5. Private IP error: device_id and device_name are required for private IP

Using a raw private IP (e.g. 10.x.x.x:7860) as the OAuth redirect URI often triggers Error 400: invalid_request from Google. nip.io maps 10.2.4.221.nip.io → 10.2.4.221 so Google sees a normal hostname.
  1. In Google Console, replace
    http://10.2.4.221:7860/api/v1/auth/google/callback
    with
    http://10.2.4.221.nip.io:7860/api/v1/auth/google/callback.
  2. Browse the app at http://10.2.4.221.nip.io:3001 (frontend) or http://10.2.4.221.nip.io:7860 (API), not the bare IP.
  3. In frontend/.env.local:
NEXT_PUBLIC_API_URL=http://10.2.4.221.nip.io:7860
NEXT_PUBLIC_WS_URL=ws://10.2.4.221.nip.io:7860
  1. For local dev, keep
    http://localhost:7860/api/v1/auth/google/callback
    in Console as well.

​
Alternative: custom hostname via /etc/hosts

Example: map 10.2.4.221 biocortex.local and use http://biocortex.local:7860/... everywhere. Every client must edit hosts; nip.io avoids that.

​
6. Summary

SymptomAction
404 on /api/v1/auth/googleStart with --frontend next; fix any “API router failed to load” at startup.
503 / not configuredSet GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET; restart.
Error after Google redirectAdd the exact callback URL used in production to Authorized redirect URIs.
400 / private IPDo not use bare private IP in redirect URI; use nip.io or a proper domain.