# Google OAuth Setup Guide

Quick reference for setting up Google OAuth authentication with Convex Auth.

## 1. Get Your Callback URL

From your `.env.local` file, find `NEXT_PUBLIC_CONVEX_URL`:

```
NEXT_PUBLIC_CONVEX_URL=https://accomplished-bass-647.convex.cloud
```

Your callback URL is: `https://accomplished-bass-647.convex.cloud/api/auth/callback/google`

## 2. Create Google OAuth Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Select or create a project
3. Enable "Google+ API" (or ensure it's enabled)
4. Navigate to: **APIs & Services** → **Credentials**
5. Click **Create Credentials** → **OAuth 2.0 Client ID**
6. Configure OAuth consent screen if prompted:
   - User Type: **Internal** (for Suno workspace only)
   - App name: Suno Spaces
   - User support email: your @suno.com email
   - Developer contact: your @suno.com email
7. Create OAuth client:
   - Application type: **Web application**
   - Name: Suno Spaces (Dev) or (Production)
   - **Authorized redirect URIs**: Add your callback URL from step 1
   - Click **Create**
8. Save your **Client ID** and **Client Secret**

## 3. Set Environment Variables in Convex

Using the Convex CLI (recommended):

```bash
npx convex env set AUTH_GOOGLE_ID your_client_id_here
npx convex env set AUTH_GOOGLE_SECRET your_client_secret_here
npx convex env set SITE_URL "http://localhost:3000"
```

**Note:** `SITE_URL` is required. For local development, use `http://localhost:3000`. For production, use your actual domain like `https://spaces.suno.run`.

Or via the Convex Dashboard:
1. Go to your [Convex Dashboard](https://dashboard.convex.dev)
2. Select your project (spaces)
3. Navigate to **Settings** → **Environment Variables**
4. Add:
   - `AUTH_GOOGLE_ID`: your Client ID
   - `AUTH_GOOGLE_SECRET`: your Client Secret
   - `SITE_URL`: `http://localhost:3000` (or your production URL)

## 4. Test Authentication

1. Start Convex dev server:
   ```bash
   npx convex dev
   ```

2. In another terminal, start Next.js:
   ```bash
   npm run dev
   ```

3. Visit `http://localhost:3000`

4. Click "Sign in with Google"

5. You should be redirected to Google OAuth

6. Sign in with a **@suno.com** email address

7. You should be redirected back to the dashboard at `/dashboard`

## Troubleshooting

### Error: "redirect_uri_mismatch"
- Double-check the redirect URI in Google Cloud Console exactly matches your callback URL
- No trailing slashes
- Format: `https://[your-deployment].convex.cloud/api/auth/callback/google` or `.convex.site` for dev

### Error: "Only @suno.com email addresses are allowed"
- This is working as intended!
- Only @suno.com emails can sign in
- To change this, edit `convex/auth.ts`

### Error: "This Convex deployment does not have HTTP actions enabled"
- Make sure `convex/http.ts` exists
- Run `npx convex dev` to push the HTTP routes

### Authentication redirects but user is null
- Check that `convex/schema.ts` includes `...authTables`
- Check that `convex/http.ts` calls `auth.addHttpRoutes(http)`
- Restart `npx convex dev`

## Production Setup

For production deployment:

1. Create a **separate** OAuth client in Google Cloud Console
2. Use your production callback URL: `https://[prod-deployment].convex.cloud/api/auth/callback/google`
3. Set environment variables in production Convex deployment
4. Update OAuth consent screen with production domain

## Environment Variable Names Reference

**Correct names** (as per Convex Auth docs):
- `AUTH_GOOGLE_ID` ✅
- `AUTH_GOOGLE_SECRET` ✅

**Incorrect names** (don't use these):
- ~~`AUTH_GOOGLE_CLIENT_ID`~~ ❌
- ~~`AUTH_GOOGLE_CLIENT_SECRET`~~ ❌