Skip to main content

Imported from docs/google-auth-setup.md. Edit source file, then re-run sync.

Google Auth Setup (Nova API + Dashboard)

This repo uses this flow:

  1. User signs in with Google in dashboard (NextAuth).
  2. Dashboard gets a Google ID token.
  3. Dashboard exchanges ID token with API (POST /v1/auth/google).
  4. API returns Nova access/refresh JWTs.

1) Create Google OAuth credentials​

Use Google Cloud Console:

  1. Go to https://console.cloud.google.com/apis/credentials
  2. Select your project.
  3. Configure OAuth consent screen if prompted.
  4. Create OAuth client ID of type Web application.
  5. Add these values:
  • Authorized JavaScript origins:
    • http://localhost:3002
  • Authorized redirect URIs:
    • http://localhost:3002/api/auth/callback/google
    • http://localhost:3002/api/integrations/google/callback

Copy:

  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET

2) Apply env configuration to both apps​

From repo root:

scripts/setup-google-auth.sh \
  --google-client-id "YOUR_CLIENT_ID" \
  --google-client-secret "YOUR_CLIENT_SECRET"

Optional flags:

  • --nextauth-url http://localhost:3002
  • --api-url http://localhost:3000
  • --project-id your-gcp-project-id

Optional dashboard override if your callback host differs from NEXTAUTH_URL:

  • GOOGLE_INTEGRATIONS_REDIRECT_URI=http://localhost:3002/api/integrations/google/callback

The script updates:

  • api/.env
  • dashboard/.env.local

For Gmail realtime sync + push verification, also set these API env vars:

  • GOOGLE_GMAIL_WATCH_TOPIC_NAME=projects/<PROJECT_ID>/topics/<TOPIC_NAME>
  • GOOGLE_PUSH_AUDIENCE=https://api.<your-domain>/v1/ingress/gmail
  • GOOGLE_PUSH_SERVICE_ACCOUNT=<service-account-email>

3) Start services​

cd api && npm run start:dev
# new terminal
cd dashboard && npm run dev

4) Verify setup​

From repo root:

scripts/verify-google-auth.sh

Then test login manually at:

  • http://localhost:3002/login

Optional gcloud helper commands​

gcloud auth login
gcloud config set project <PROJECT_ID>

Then open credentials page:

  • https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>

Pub/Sub setup for Gmail watch (production)​

  1. Create topic:
gcloud pubsub topics create nova-gmail-watch
  1. Create push subscription to Nova API global endpoint:
gcloud pubsub subscriptions create nova-gmail-watch-sub \
  --topic=nova-gmail-watch \
  --push-endpoint="https://api.<your-domain>/v1/ingress/gmail" \
  --push-auth-service-account="<service-account-email>" \
  --push-auth-token-audience="https://api.<your-domain>/v1/ingress/gmail"
  1. Copy values into API env/GitHub secrets:
  • GOOGLE_GMAIL_WATCH_TOPIC_NAME=projects/<PROJECT_ID>/topics/nova-gmail-watch
  • GOOGLE_PUSH_SERVICE_ACCOUNT=<service-account-email>
  • GOOGLE_PUSH_AUDIENCE=https://api.<your-domain>/v1/ingress/gmail

Troubleshooting​

  • redirect_uri_mismatch
    • Ensure both redirect URIs are registered exactly:
      • http://localhost:3002/api/auth/callback/google
      • http://localhost:3002/api/integrations/google/callback
    • If your app is accessed on a different host (for example 127.0.0.1, custom domain, or tunnel), register that exact host variant too, or set GOOGLE_INTEGRATIONS_REDIRECT_URI to the registered URI.
  • Sign-in fails with Nova auth error
    • Ensure dashboard/.env.local has correct API_URL and API is running.
    • Ensure api/.env and dashboard/.env.local use the same Google client ID/secret.
  • CORS errors
    • Ensure API CORS_ORIGINS includes dashboard origin (http://localhost:3002).
  • Gmail push 401 / Unauthorized
    • Ensure Pub/Sub subscription uses OIDC authentication.
    • Ensure audience exactly matches API setting and push endpoint:
      • https://api.<your-domain>/v1/ingress/gmail
    • Ensure GOOGLE_PUSH_SERVICE_ACCOUNT matches the subscription service account.