AdPlatform-Server/GoogleApi/GOOGLE_ADS_SETUP.md

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

# ==========================================
# 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:

# 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

# 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

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

Expected response:

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

Test API Call (via Gateway)

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