Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wizpay.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Circle Google Login Audit

​
Scope

This checklist covers the Google social login flow used by the existing Circle User-Controlled Wallet integration in this repo. It is based on the current frontend and backend implementation, not on a hypothetical future auth stack. Key runtime anchors:
  • NEXT_PUBLIC_CIRCLE_APP_ID
  • NEXT_PUBLIC_GOOGLE_CLIENT_ID
  • CIRCLE_API_KEY
  • Google redirect URI derived from window.location.origin
Relevant code paths:
  • frontend Google login config is built in apps/frontend/services/circle-auth.service.ts
  • the login config uses window.location.origin as the redirect URI
  • backend wallet persistence happens through POST /wallets/initialize, POST /wallets/sync, and POST /wallets/ensure

​
Symptom Map

Use the symptom first, then jump to the matching checklist item.

​
155114

The Circle app ID does not match the active wallet app. Check:
  1. NEXT_PUBLIC_CIRCLE_APP_ID
  2. the active User-Controlled Wallet app in Circle Console
  3. whether the frontend env was updated after creating a new Circle app

​
155140 after browser-side checks already passed

State, nonce, and client ID looked valid in the browser, but Circle still rejected the Google token. Most likely cause:
  1. the Google client ID is not enabled on the same Circle User-Controlled Wallet app as NEXT_PUBLIC_CIRCLE_APP_ID

​
POST /wallets/sync fails with DATABASE_UNREACHABLE

This is not a Google OAuth misconfiguration. Most likely cause:
  1. the backend is running on the host with Docker-only env values such as DATABASE_URL=...@postgres:5432/...
  2. Postgres is not reachable from the host runtime

​
Required Circle Console Checks

​
1. Project And Environment Match

Confirm these belong to the same Circle project and environment:
  1. CIRCLE_API_KEY
  2. NEXT_PUBLIC_CIRCLE_APP_ID
  3. the Google social login provider attached to the Circle app
Do not mix:
  1. a test API key with a live Circle app
  2. a live API key with a test Circle app
  3. a Google provider attached to a different Circle project

​
2. The App ID Really Points To The Active UCW App

Open Circle Console and verify that NEXT_PUBLIC_CIRCLE_APP_ID is the exact app ID of the User-Controlled Wallet app used for Google login in this repo. If you recently recreated the Circle app, rotate the frontend env as well. Reusing the old app ID after migrating the Google provider is a common failure mode.

​
3. Google Is Enabled On That Exact App

Inside Circle Console, verify that Google social login is enabled on the same UCW app referenced by NEXT_PUBLIC_CIRCLE_APP_ID. Do not assume a Google provider enabled on another UCW app in the same project will work here.

​
4. The Google Client ID Matches The App Configuration

Verify that the Google OAuth client configured in Circle Console is exactly the same value as NEXT_PUBLIC_GOOGLE_CLIENT_ID. If Circle rejects the token after the browser-side state, nonce, and client ID checks pass, this is the first thing to re-check.

​
5. Redirect URI And Origin Match The Current Frontend Runtime

This repo builds the Google login config with window.location.origin as the redirect URI. That means the Google OAuth client must allow the exact frontend origin you are using, for example:
  1. http://localhost:3000 for local dev
  2. the production origin for the deployed app
  3. any staging origin you actually use
If you run the frontend on a different local port, that exact origin must also be allowed.

​
6. The Redirect Destination Must Match What The Repo Sends

Because the redirect URI is derived from the page origin, do not whitelist only a backend callback URL if the browser is actually returning to the frontend origin. For this repo, the safe assumption is:
  1. the Google redirect comes back to the frontend origin
  2. Circle validates that returned Google token against the app and provider configuration
Check the Google Cloud OAuth client used by NEXT_PUBLIC_GOOGLE_CLIENT_ID and confirm:
  1. authorized JavaScript origins include the active frontend origin
  2. authorized redirect URIs include the same frontend origin used by this repo
  3. the OAuth client is not disabled or rotated without updating env

​
8. Old Browser State Must Be Cleared After Config Changes

If you changed the Circle app ID, Google client ID, or redirect setup, clear old OAuth state before retrying. This repo caches:
  1. OAuth state
  2. OAuth nonce
  3. Circle device token
  4. Circle device encryption key
  5. Google client ID markers in cookies and local storage
Without clearing those, the browser can look partially correct while still replaying stale pre-login state.

​
9. Email OTP Fallback Should Still Work

If Google login fails but email OTP succeeds, that usually narrows the issue to Circle app and Google provider configuration, not the whole W3S integration.

​
10. Backend Wallet Sync Is A Separate Layer

A successful Google redirect is still followed by backend wallet initialization and sync. If login reaches backend wallet sync and then fails, audit these separately:
  1. DATABASE_URL
  2. Postgres reachability
  3. REDIS_HOST only if background workers are part of the failing flow
In local host-run mode, Docker-only hosts such as postgres and redis must be translated to host-reachable values.
  1. Confirm NEXT_PUBLIC_CIRCLE_APP_ID and NEXT_PUBLIC_GOOGLE_CLIENT_ID in env.
  2. Confirm both values point to the same UCW app in Circle Console.
  3. Confirm Google is enabled on that app.
  4. Confirm Google Cloud origins and redirect URIs include the exact frontend origin.
  5. Clear browser OAuth state and retry.
  6. If Google login now succeeds but /wallets/sync fails, switch to backend env validation rather than Circle Console debugging.