# Google Ads API Configuration Guide

## Overview

This document describes how to configure the GoogleApi service to connect to the real Google Ads API. The service supports both **emulated mode** (for testing without Google credentials) and **real API mode**.

## Configuration Levels

| Level | Storage | Examples |
|-------|---------|----------|
| **Platform secrets** | Azure Key Vault | Developer token, OAuth client secret |
| **Platform config** | App Settings / appsettings.json | API version, timeouts |
| **Per-account credentials** | Database (tbGoogleCredential) | Refresh tokens per linked account |

## Quick Start (Test Account)

1. Create a Google Ads test manager account
2. Get a developer token (works immediately for test accounts)
3. Set up OAuth credentials in Google Cloud Console
4. Configure the environment variables below

## Environment Variables for Azure Container Apps
> **Note:** This service runs **server-to-server**. There is **no interactive OAuth UI** at runtime.
> Generate the refresh token once (out-of-band) and store it securely (Key Vault / secrets).


### GoogleApi Service

```bash
# ==========================================
# Core Settings
# ==========================================

# Enable real Google Ads API calls (default: false)
GoogleAds__EnableRealApi=true

# API version (default: v22)
GoogleAds__ApiVersion=v22

# ==========================================
# Authentication - Developer Token
# Required for all API calls
# ==========================================

# Your developer token from Google Ads API Center
# Format: 22-character alphanumeric string
# Get from: https://ads.google.com/aw/apicenter
GoogleAds__DeveloperToken=YOUR_DEVELOPER_TOKEN_HERE

# ==========================================
# Authentication - OAuth 2.0
# Required for authenticating API requests
# ==========================================

# OAuth Client ID from Google Cloud Console
GoogleAds__OAuth__ClientId=YOUR_CLIENT_ID.apps.googleusercontent.com

# OAuth Client Secret from Google Cloud Console
# SENSITIVE - Use Key Vault reference in production
GoogleAds__OAuth__ClientSecret=YOUR_CLIENT_SECRET

# Refresh token for platform-level access
# Generated via OAuth flow or gcloud CLI
# SENSITIVE - Use Key Vault reference in production
GoogleAds__OAuth__RefreshToken=YOUR_REFRESH_TOKEN

# ==========================================
# Manager Account (Optional)
# Required if accessing client accounts under a manager
# ==========================================

# Default login customer ID (manager account)
# Format: 1234567890 (no dashes)
GoogleAds__DefaultLoginCustomerId=1234567890

# ==========================================
# Internal Authentication
# For Gateway -> GoogleApi communication
# ==========================================

# Shared secret for internal API authentication
# SENSITIVE - Use Key Vault reference
GOOGLE_INTERNAL_KEY=your-secure-internal-key

# ==========================================
# Optional Settings
# ==========================================

# HTTP timeout in seconds (default: 60)
GoogleAds__TimeoutSeconds=60

# Max retry attempts (default: 3)
GoogleAds__MaxRetries=3
```

### Azure Key Vault References

For sensitive values, use Key Vault references in Azure Container Apps:

```bash
# Instead of plain values:
GoogleAds__DeveloperToken=@Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/GoogleAdsDeveloperToken/)
GoogleAds__OAuth__ClientSecret=@Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/GoogleAdsClientSecret/)
GoogleAds__OAuth__RefreshToken=@Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/GoogleAdsRefreshToken/)
GOOGLE_INTERNAL_KEY=@Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/GoogleInternalKey/)
```

## Step-by-Step Setup

### 1. Create Google Ads Manager Account

1. Go to https://ads.google.com/aw/apicenter
2. Sign in with a Google account NOT linked to production ads
3. Create a new manager account
4. For test accounts, click "Create a test manager account" link

### 2. Get Developer Token

1. In your manager account, go to **Tools & Settings > API Center**
2. Your developer token will be displayed
3. For test accounts: Token works immediately
4. For production: Apply for Basic Access (takes a few days)

### 3. Create Google Cloud Project

1. Go to https://console.cloud.google.com
2. Create a new project (or use existing)
3. Enable the **Google Ads API**:
   - Go to APIs & Services > Library
   - Search "Google Ads API"
   - Click Enable

### 4. Create OAuth Credentials

1. Go to APIs & Services > Credentials
2. Click **Create Credentials > OAuth client ID**
3. Application type: **Desktop app** (for initial testing)
4. Download the JSON file
5. Note the Client ID and Client Secret

### 5. Generate Refresh Token

Option A: Using gcloud CLI
```bash
# Install gcloud CLI if not installed
gcloud auth login --cred-file=path/to/client_secret.json

gcloud auth print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'
```

Option B: Using OAuth Playground
1. Go to https://developers.google.com/oauthplayground/
2. Click gear icon > Use your own credentials
3. Enter your Client ID and Secret
4. Select Google Ads API scope: `https://www.googleapis.com/auth/adwords`
5. Click Authorize APIs, sign in
6. Click "Exchange authorization code for tokens"
7. Copy the Refresh Token

### 6. Create Test Client Account

1. In your test manager account
2. Click Accounts > + > Create new account
3. This creates a test client account under your manager
4. Note the Customer ID (format: XXX-XXX-XXXX)

### 7. Configure Azure Container App

In Azure Portal > Container Apps > Your GoogleApi App > Settings > Environment Variables:

Add each variable from the list above, using Key Vault references for sensitive values.

## Testing the Configuration

### Check Health Endpoint

```bash
curl https://your-googleapi-url/health
```

Expected response:
```json
{
  "service": "GoogleApi",
  "status": "healthy",
  "config": {
    "realApiEnabled": true,
    "apiVersion": "v18",
    "developerTokenSet": true,
    "oauthConfigured": true,
    "defaultLoginCustomerId": "1234567890"
  }
}
```

### Test API Call (via Gateway)

```bash
curl -X POST https://your-gateway-url/api/execution/request \
  -H "Content-Type: application/json" \
  -H "X-Dev-ClientId: test-client" \
  -H "X-Dev-TenantId: 1234567890" \
  -d '{
    "operation": "ListAccessibleCustomers",
    "payload": {}
  }'
```

## Credential Flow Diagram

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Gateway   │────▶│  GoogleApi  │────▶│ Google Ads  │
└─────────────┘     └─────────────┘     │    API      │
                           │            └─────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
              ┌─────▼─────┐  ┌────▼────┐
              │  Config   │  │ Database │
              │(env vars) │  │(per-acct)│
              └───────────┘  └──────────┘
              
Config provides:           Database provides:
- Developer Token          - Per-account refresh tokens  
- OAuth Client ID/Secret   - Account-specific credentials
- Default refresh token    - Linked customer IDs
```

## Troubleshooting

### "UNAUTHENTICATED" Error
- Check developer token is correct
- Verify OAuth credentials
- Ensure refresh token hasn't expired

### "PERMISSION_DENIED" Error  
- Developer token may not be approved for production
- Verify account access permissions
- Check login-customer-id is correct

### "INVALID_CUSTOMER_ID" Error
- Customer ID format should be 10 digits, no dashes
- Verify account exists and is accessible

### Token Exchange Fails
- Client ID/Secret mismatch
- Refresh token was revoked
- OAuth consent was withdrawn

## Security Best Practices

1. **Never commit secrets** to source control
2. **Use Azure Key Vault** for all sensitive values
3. **Rotate refresh tokens** periodically
4. **Audit API access** via tbAdpApiLog
5. **Limit developer token access** - one token per application
6. **Use test accounts** for development and testing