Connect your first ad platform

A "connection" in SEM is just an OAuth link between your SEM workspace and an ad network. Once it's in place, we pull your account list, campaigns, and 30-day metrics on a schedule. Your tokens are encrypted at rest and we never see your password — only the access token the platform issues.

How the OAuth flow works

1. 1
   Click 'Connect →' on the Connections page

   Pick Google, Meta, Microsoft, Nextdoor, or CGMIMM Ads. We send you to that platform's official sign-in page.
2. 2
   Sign in with the account that owns your ad accounts

   Important: it has to be the user that has access to the ad accounts you want to manage. If you're an agency with sub-accounts (MCC for Google, Business Manager for Meta), use the parent.
3. 3
   Approve the requested permissions

   We ask for read + write to your ad data. Read is for reporting; write is for future features (pause/edit campaigns from inside SEM).
4. 4
   You're redirected back to /connections

   The connection appears in the table with status = active. Click Sync to pull accounts and campaigns.

Per-platform notes

Google Ads

The most common connection. Sign in with the email that owns your Google Ads account or your MCC (Manager) account. We use the Google Ads API v18 with GAQL queries to pull campaign list, status, budget, and last-30-day metrics (impressions, clicks, spend, conversions, conversion value).

Meta (Facebook + Instagram)

Sign in with your Facebook account that has access to the ad accounts. We request the ads_read, ads_management, and business_management permissions. Tokens issued by Meta last about 60 days — we refresh them automatically.

Microsoft Ads (Bing)

Uses Microsoft identity OAuth. Most useful if you're already running Google Ads — Microsoft typically delivers cheaper clicks for the same intent, especially for B2B and an older demographic.

Nextdoor Ads

Best for local-only businesses. The Nextdoor Ads API is a partner-approval program; if you don't already have an Ads Manager account, you'll apply for one through Nextdoor first.

CGMIMM Ads

Internal ad network across the CGMIMM property network. Currently uses an API-key handshake (you paste a key from your CGMIMM account); a full OAuth flow ships in a future update.

What 'Sync' does

When you click Sync on a connection, three things happen in order:

• Token refresh — if the access token is close to expiring, we use the refresh token to mint a new one.
• Account discovery — we ask the platform "what ad accounts can this user see?" and store them in your workspace.
• Campaign pull — for each non-manager account, we fetch every campaign and 30 days of metrics.

After sync, your campaigns show up on /campaigns and your dashboard tile updates with cross-platform totals.

Troubleshooting

• "State mismatch" error. This means the OAuth round-trip lost its CSRF token — usually because cookies are blocked or you took longer than 10 minutes between starting and finishing. Just click Connect again.
• Connection succeeds but Sync returns no accounts. The user you signed in with has no ad accounts attached. Sign in with a different account, or have the owner add you to theirs first.
• Campaigns are syncing but metrics are zero. Either no spend in the last 30 days, or your account is too new — Google Ads sometimes takes 24h to backfill metrics for new campaigns.