Platforms

Platform Access, API Limits & Readiness

Created 11 Jun 2026·Updated 12 Jun 2026

Latest change: Meta CPAS Phase 2 core track; API vs manual TBD; shared-item metrics

Purpose

Phase 0 gate document for implementation. Before writing connectors or onboarding real clients, Kobi must secure platform contracts, developer approvals, OAuth/scopes, billing instruments, test accounts, and rate-limit headroom.

This doc consolidates:

  • Legal entity and Google Cloud foundation
  • Required API scopes vs platform capability — with red flags where scope or product access is missing
  • Account structural limits (BM, BC, MCC, credit lines)
  • Rate limits and a gameplan to increase them
  • Activation prerequisites (system users, billing, verification)
  • Test / sandbox accounts for pilot clients
  • Cross-cutting items identified from the rest of the doc set

Verify at implementation — platform policies and numeric limits change. Every row links to official docs; re-validate before Phase 1 kickoff.

How to use this document

Phase Action
Now (Phase 0) Work through Pre-implementation checklist; open red-flag rows in Scope & capability matrix
Phase 1 start Google entity + Cloud org + Ads Basic token + internal OAuth + test MCC accounts
Phase 2 Meta Marketing API Full tier + TikTok Live app + BM/BC credit paths proven
Phase 3 DV360 contract + partner/advertiser API identities
Ongoing Connector middleware parses rate-limit headers; System Ops dashboard shows quota burn

Item Requirement Red flag if missing
Operating legal entity Registered company (TR/EU entity TBD with legal) matching invoices, ad platform billing, and OAuth consent screen Cannot pass Google/Meta/TikTok business verification
Partner relationships (VC-owned) Warm intros to Google / Meta / TikTok partner reps — 2-Tier BM (PRE-10), Meta credit (PRE-2), TikTok BC headroom. Not engineer cold outreach. W0 VC gate Meta scaling + TikTok escalation stall indefinitely
Google Cloud organization GCP org under company domain; projects kobi-ads-dev, kobi-ads-staging, kobi-ads-prod No IAM boundary for secrets, Vertex, BigQuery
Cloud Billing account Linked to legal entity; budgets + alerts per project Vertex / Cloud Run blocked
Google Workspace (recommended) Domain for @company users, DV360 service-account delegation, group-based IAP DV360 service-account impersonation harder with @gmail.com only
Domain & website Public site with Privacy Policy, Terms, product description TikTok app review rejects; Google OAuth external verification delayed
DPA / sub-processor list Client contracts reference Google, Meta, TikTok, etc. Onboarding consent flow incomplete — see vision

Start internal-first: use Internal Google OAuth consent screen and workforce identities for Phase 1 pilots. Plan External verification before multi-tenant SaaS or sensitive scopes at scale.


Scope & capability matrix (red flags)

Kobi-required capabilities mapped to API access. If a row is blocked or partial, raise an internal red flag ticket (engineering — not client HITL) and do not promise that capability in SKU until resolved.

Capability Required scope / product Status Red flag
Read/write campaigns, ad groups, ads, assets Google Ads API + developer token; OAuth scope https://www.googleapis.com/auth/adwords Required No developer token or token stuck at Test-only
MCC create / link client shells MCC admin + Ads API CustomerService.CreateCustomerClient Required MCC not established under entity; new/low-spend MCC may be ineligible to create accounts via API (CREATION_DENIED_INELIGIBLE_MCC) — see account-creation limits
Offline conversion import ConversionUploadService / ConversionAdjustmentUploadService Required CRM loop blocked
GA4-linked conversions GA4 ↔ Ads link (UI + API read) Required Optimization uses wrong SoT
Performance Max mutate Ads API PMax resources Partial Some asset-group / listing-group operations still restrictive — validate per API version
Shopping / Merchant Center feed Content API for Shopping (separate from Ads API) Required for ecommerce SKU Feed connector blocked
Merchant Center account structure MCA + sub-accounts API Required for ecommerce Shopping launch blocked
Billing setup on account Agency MCC billing — one-time PRE-1 🔧 PRE New accounts inherit; not per-client red flag
Invoicing / monthly pass-through Kobi ERP invoices client monthly N/A Not a Google/Meta API

OAuth verification: adwords is a sensitive scope. External OAuth apps need Google OAuth verification + acceptable use review. Mitigation: Internal consent + Workspace users first; service-style refresh token on dedicated automation Google user under MCC.

GA4 (measurement)

Capability Required scope / product Status Red flag
Read reports Analytics Data API Required Reporting/optimization blind
Admin: streams, events, conversions Google Analytics Admin API Required Cannot automate setup
Measurement Protocol (server events) API secret per stream Required sGTM / server events blocked
BigQuery export (client GCP) Admin UI + client project Out of Kobi scope Client optional; Kobi uses Analytics Data API
Google Ads → BigQuery (Kobi GCP) Data Transfer + MCC access Required Kobi reporting / invoice reconcile blocked for Google
Google Ads cost import Product link (UI) Required GA4 SoT incomplete

Scopes (typical): analytics.readonly, analytics.edit — verify least-privilege split between read-only reporting SA and setup SA.

Meta Ads (Marketing API)

Capability Required permission / product Status Red flag
Create/manage campaigns ads_management Required Core Meta connector blocked
Insights / reporting ads_read Required Optimization blocked
BM / ad account / system user business_management Required Cannot assign system user via API
Page + IG ads pages_manage_ads, pages_read_engagement (as needed) Required Creative / Page-linked ads fail
Catalog / product feed Catalog API + catalog_management Required for dynamic ads Ecommerce Meta blocked
Collaborative Ads (CPAS) Catalog segment share + catalog_segment_id campaigns; Insights shared-item metrics Phase 2🔧 API vs manual TBD per marketplace CPAS spec; retailer onboarding partly UI-only on Meta
Conversions API Pixel + CAPI endpoint (access token) Required No server-side optimization
Offline conversions Offline event set API Optional CRM path incomplete
Special Ad Categories special_ad_categories on every campaign (HOUSING, EMPLOYMENT, FINANCIAL_PRODUCTS_SERVICES, ISSUES_ELECTIONS_POLITICS, or NONE) Required field (value NONE unless ad concerns those topics) Wrong/missing value → disapproval. Schools & health are not categories — default NONE
API ad-account / tenant model 2-Tier BM (child BM per client) — ADR 0003; owned_businesses + client OAuth 🔧 PRE-10 Production 2-Tier blocked until Meta rep grants access; single-BM fallback (≤5) interim
Credit line / extended credit Business Manager billingone-time PRE-2 🔧 PRE Agency master; accounts inherit; not per-client red flag

App Review: Marketing API Limited tier by default. Full tier needed for production rate limits — see Meta rate limits.

TikTok Ads (Marketing API)

Capability Required scope / product Status Red flag
Advertiser CRUD / campaigns TikTok Marketing API — Advertiser scopes Required Connector blocked until app Live
Reporting / insights Reporting endpoints per app approval Required Optimization blocked
Events API (server) Events API access + pixel Required Server events blocked
Catalog / catalog ads Catalog-related endpoints (if in SKU) Partial Confirm scopes in app review — ecommerce gap
Spark Ads Organic + ads authorization APIs Partial Human workflow required; API may not cover all Spark flows
BC admin assignment Business Center UI + API advertiser role Required API app cannot access advertisers without BC admin
Billing / prepaid BC agency funding — one-time PRE-3 🔧 PRE Not per-client red flag

Critical path: TikTok for Developers app → Sandbox first → App Review (demo video, privacy policy, functional prod UI) → Live with Marketing API scopes. Timeline: manual, days–weeks, no guaranteed SLA.

DV360 (Display & Video 360 API)

Capability Required scope / product Status Red flag
IO / line item mutate https://www.googleapis.com/auth/display-video Blocked until GMP contract Entire DV360 phase deferred
User management (automation) display-video-user-management (service account) Optional Use UI for break-glass only
Floodlight / CM360 Campaign Manager 360 API (separate product) Optional If CM360 chosen over GA4-only path — second sales cycle
Programmatic guaranteed deals UI / sales contracts Not API-automatable Human-only per dv360.md

Sales partner: DV360 access requires Google Marketing Platform contract via Google sales — not self-serve. Plan months for entity vetting and minimum spend commitments.

Internal CRM

Capability Required Status Red flag
Webhook POST /integrations/crm/conversions Internal API Required for closed loop Phase 4 dependency
Click IDs (gclid, fbclid, ttclid) on entities Schema Required Attribution broken

No external platform approval — but CRM team must deliver contract before CAPI maturity.


Rate limits & increase gameplan

Cross-platform connector rules (mandatory)

  1. Parse platform rate-limit headers on every response (see per-platform table).
  2. Central quota scheduler in orchestrator — serialize mutates per account, prioritize human-blocked work.
  3. Exponential backoff + jitter; distinguish retryable vs quota exhausted.
  4. Emit connector.rate_limit.{platform} events → System Ops dashboard.
  5. Batch where supported (Meta /batch, Google BatchJobService, Ads SearchStream for reads).
Tier Daily operations (sliding 24h) How to obtain Increase gameplan
Test Account Access 15,000 (test only) Default with test token Use for CI / connector tests
Explorer 2,880 prod / 15,000 test Legacy — avoid Migrate to Basic
Basic 15,000 prod + test Apply (~2 business days) Phase 1 default — enough for ~50–150 tenants at light automation if reads are efficient
Standard Unlimited daily ops (system rate limits still apply) Standard Access application (~10 business days) + RMF compliance Apply when tenant count × optimization frequency exceeds ~10k ops/day

System rate limits: per-minute/hour caps still apply at Standard — use SearchStream, field masks, batch jobs, caching.

Red flag: Standard Access denied → cap pilot tenant count or reduce optimization cadence.

Sources: Access levels, Quotas.

CustomerService.CreateCustomerClient is Restricted Functionality (Basic/Standard token, not Test) and is gated — the Meta-style "can't create the account" risk applies here too:

Constraint Detail Mitigation
New/low-spend MCC ineligible Manager accounts below spend thresholds or without enough active, policy-compliant child accounts get CREATION_DENIED_INELIGIBLE_MCC (enforced since Mar 2025) Chicken-and-egg — seed the MCC with manual/UI-created accounts + real spend before relying on API creation; verify eligibility in Phase 0 (B11)
Weekly creation cap 2,500 accounts / week per manager Non-binding at pilot/growth; relevant only at mass scale
Frequency quota Burst creation → QuotaError.RESOURCE_EXHAUSTED; honor retry_delay (~30 s) Serialize creation in the quota scheduler; backoff
Policy / hard caps ACCOUNT_CREATION_POLICY_VIOLATION, MAX_CUSTOMER_LIMIT_REACHED; 85,000 total linked accounts; active-account limit scales with 12-mo spend Handle error codes explicitly; break-glass to UI creation

Parallel to Meta B1: unlike Meta there's no fixed "5" — but a fresh MCC may simply refuse API account creation until it has spend history. Treat MCC eligibility as a Phase-0 gate, not an assumption.

Sources: Account limits, CreateCustomerClient changes (Mar 2025).

Meta Marketing API

Tier Typical limit (ads_management, per ad account / hour) How to obtain Increase gameplan
Limited (dev) 300 + 40 × active ads Default on new app Phase 1 dev only
Full 100,000 + 40 × active ads Marketing API Access Tier upgrade: 500+ calls / 15 days, <15% error rate on last 500 calls Submit App Review; monitor X-Business-Use-Case-Usage — backoff at 80%

Additional: Business Use (BU) scoring per call; use /batch (up to 50 sub-requests). Business verification unlocks higher spend limits (separate from API tier).

Red flag: Stuck on Limited with production tenants → throttled automation, missed optimization windows.

TikTok Marketing API

Stage Access How to obtain Increase gameplan
Sandbox Test advertisers only Developer app created Build OAuth + core CRUD
Live / Production Real advertisers App Review + business verification Submit early Phase 1; parallel legal review
Rate limits Endpoint-specific (documented per API version) Shown in developer portal Request quota review via TikTok rep after consistent Live usage

Red flag: App not Live before Phase 2 launch date → Meta-only or manual TikTok ops.

DV360 API

Limit Notes Increase gameplan
No separate developer token OAuth per DV360 user / service account Ensure Admin grants on partner + advertisers
Standard Google Cloud quotas API enablement on GCP project Request quota increase in Cloud Console if needed

GA4 APIs

API Quota Increase gameplan
Analytics Data API Property-level tokens per hour Reduce polling; use BigQuery export for heavy reporting
Admin API Low write quotas Batch setup in onboarding, not per-minute

Account structure, billing & activation

Item Detail
Hierarchy Kobi MCC → client shell accounts (google-ads.md)
Developer token Registered to MCC; keep in Secret Manager
Automation identity Dedicated Google user or OAuth refresh token with Standard access on MCC
Billing Agency billing profile on MCC / per account — no client card
Test accounts Create via MCC for connector CI — no live impressions
Business / identity verification Kobi entity on MCC — PRE-7; MCC Verification Hub (bulk) + API status poll
Activation Agency billing + identity verified + conversion actions + (optional) Merchant link

Meta Ads

Item Detail
BM / Business Portfolio Parent BM (Kobi) → child BM per client via 2-Tier (ADR 0003). Fallback: ≤5 ad accounts on parent BM until PRE-10
Ad account creation limit (single BM) API cap 5 per BM (Meta help) — use 2-Tier instead of stacking accounts
Per-user manage limit 25 ad accounts per person
System user Create in BM; assign ad account + pixel + catalog assets; token in Secret Manager
System user limit Low default — increases with Marketing API Access Tier / app history
Credit line Extended credit or invoicing through Meta — required for agency-scale billing without per-account cards; human sales/finance setup
Business verification Kobi entity on BM — PRE-8; unlocks limits + trust
Activation Verified BM + system user token + Page linked + pixel + CAPI

TikTok Ads

Item Detail
Business Center Kobi BC → advertiser per tenant
Advertiser-account creation limit Default cap on advertiser accounts per BC — varies by BC type; raise only via TikTok account manager (help). API: POST /bc/advertiser/create/. Relationship-gated like Meta 2-Tier — confirm headroom in Phase 0
Developer app TikTok for Developers — Marketing API product enabled
Approval Privacy policy, ToS, demo video, production URL, scope justification
BC admin Must assign advertiser to approved app / user
Billing Agency billing / prepaid per advertiser — funding thresholds trigger human touch
Business verification Kobi entity on BC — PRE-9
Activation Live app + verified BC + OAuth token + pixel + Events API

DV360

Item Detail
Contract Google Marketing Platform sales — not API-gated without product
Partner / advertiser Created under Kobi partner ID
API user Standard or Admin role on partner/advertiser
Billing Agency invoice — separate from Ads MCC

GA4

Item Detail
Access Editor for automation; client retains ownership where possible
Activation Stream live + events firing + BigQuery link + Ads link

Test & pilot accounts (small business)

Plan 2–3 pilot tenants before general availability:

Platform Test approach
Google Ads MCC test account (API test token) + one real small-spend shell for E2E
Meta Dedicated ad account under Kobi BM; low daily cap; use Limited tier app in dev, Full tier before multi-tenant
TikTok Sandbox advertiser → migrate to Live app with single pilot advertiser
GA4 Kobi-owned test property + client-owned pilot property
DV360 Defer until contract — use Google Ads Display campaigns as interim if needed
CRM Staging tenant with synthetic conversions

Criteria for pilot exit: onboarding < SLA, GA4 green, one full plan → execute → optimize cycle, CRM event round-trip on at least Google + one social platform.


Pre-implementation checklist (🔧 PRE — one-time; no per-client onboarding warnings)

Agency billing, Kobi-entity business verification, monthly platform invoicing, MCA, TikTok app Live, etc. are configured once before the first client. Onboarding connectors inherit these defaults — they do not emit platform.onboarding.red_flag or ONB tickets for billing or business verify. See PRE register.

PRE ID Item
PRE-1 Google MCC + monthly invoicing
PRE-2 Meta extended credit / agency invoice
PRE-3 TikTok BC agency funding
PRE-4 Agency Merchant Center MCA
PRE-5 TikTok developer app Live
PRE-6 DV360 GMP contract
PRE-7 Google MCC business / identity verificationKobi entity (MCC Verification Hub bulk OK)
PRE-8 Meta BM business verificationKobi entity
PRE-9 TikTok BC business verificationKobi entity
PRE-10 Meta 2-Tier Business Manager access — request via Meta rep. Primary production path: child BM per client from client #1 (setup guide, owned_businesses). Dev mode: test 2-Tier directly (~2 child BMs typical pre-review). Fallback: single parent BM ≤5 ad accounts until PRE-10 lands — ADR 0003

Per-client spend comes from approved plans (budget mutate APIs + Meta spend_cap + internal guardrails) — not from client payment instruments.

Business verification uses the Kobi legal entity by default — not client incorporation docs. Shell accounts inherit verified agency masters. Domain verification (client website DNS) is separate and optional per tenant.

Entity & cloud (Week 0–2)

  • Legal entity and bank instruments for platform billing
  • GCP org + projects + billing + budget alerts
  • Public website + privacy + terms (TikTok / OAuth prerequisite)
  • Secret Manager + rotation runbook (security)

Google (Phase 1 gate)

  • MCC created under Kobi legal entity
  • MCC business / advertiser identity verification complete (Verification Hub; bulk across managed accounts)
  • Google Ads API developer token — Basic minimum
  • OAuth client — Internal first; document path to External verification
  • Test MCC accounts for CI
  • Pilot Merchant Center MCA (if ecommerce SKU)
  • GA4 Admin + Data API credentials

Meta (Phase 2 gate)

  • Kobi Business Portfolio + billing instrument / credit line path
  • Developer app + Marketing API product
  • System user SOP documented
  • Marketing API Access Tier Full (or dated plan to reach 500 calls / 15 days)
  • Kobi entity business verification submitted on BM (not per-client)
  • CAPI subdomain / relay ready

TikTok (Phase 2 gate)

  • Business Center admin access
  • Kobi entity business verification on BC (not per-client)
  • Developer app — Sandbox integration complete
  • App Review submitted for Marketing API Live access
  • Demo video + scope documentation prepared
  • Events API test pixel on pilot site

DV360 (Phase 3 gate)

  • Google sales engagement started (Phase 0)
  • DV360 contract signed
  • Partner + test advertiser + API user roles
  • GCP OAuth or service account for display-video scope

Cross-cutting

  • Scope matrix red flags all resolved or accepted with SKU caveats
  • Rate-limit middleware spec in connector design
  • System Ops dashboard quota panels (system-ops-dashboard.md)
  • Break-glass human admins documented per platform

Additional considerations (from doc review)

Items not fully covered in individual platform specs but blocking or risky:

# Topic Risk Mitigation
1 Google OAuth External verification adwords scope blocked for public clients Internal OAuth → dedicated automation user; plan verification 4–8 weeks
2 Google Ads RMF Standard Access requires Required Minimum Functionality Track Google policy checklist before Standard application
3 Meta credit line / invoicing Per-account cards do not scale Finance opens agency extended credit early
4 Meta 2-Tier / single-BM fallback Production onboarding without PRE-10 2-Tier primary (ADR 0003); PRE-10 via Meta rep; fallback parent BM ≤5 until granted; test 2-Tier in dev
5 TikTok app review latency Phase 2 slip Start review in Phase 1; sandbox parallel build
6 TikTok BC ↔ app advertiser assignment Token cannot see tenant Automate BC assignment checklist in onboarding
7 DV360 sales cycle Months, minimum spend Start sales in Phase 0; keep DV360 out of early SKU
8 CM360 / Floodlight Second GMP product if legacy attribution chosen Prefer GA4-only path per dv360.md
9 Merchant Center policy Feed disapprovals block Shopping Human touch + feed validator agent
10 PMax / ASC API surface Not all UI features in API Plan templates match API-supported structures only
11 Special Ad Categories (Meta) Only HOUSING/EMPLOYMENT/FINANCIAL_PRODUCTS_SERVICES/ISSUES_ELECTIONS_POLITICSschools & health are NOT categories (default NONE); EU bans political ads (TTPA) Per-ad classification + QC; do not default verticals to a category (meta-ads.md)
12 Domain verification (client site) Meta / Google blocking optimization events Implementation guide — separate from Kobi-entity business verify (PRE)
13 Consent Mode v2 (EEA/UK) Legal + tag risk Client sign-off in onboarding (ga4-source-of-truth.md)
14 Multi-tenant token storage One agency app, many tenants Per-tenant platform IDs in registry; never cross-wire tokens
15 Break-glass admins API user lockout MCC / BM / BC break-glass humans (security)
16 No platform invoice API Client monthly invoice is Kobi ERP Do not scope ERP on Google/Meta billing APIs
17 Spark Ads (TikTok) Partial automation Human approval path in tiktok-ads.md
18 Realtime webhooks Meta/TikTok change notifications Optional Phase 2+ — polling acceptable initially
19 API version pinning Breaking changes Pin Marketing API / Google Ads API versions; quarterly upgrade cadence
20 Turkey / EU entity Data residency, billing, TikTok/Meta regional rules Align with GCP region + legal
21 Client GA4 / MMP BigQuery Scope creep if Kobi owns client analytics warehouse Out of scope — Kobi exports Google Ads only; GA4 via Data API — see Data warehouse responsibility
22 Google Ads API account-creation eligibility New/low-spend MCC can be refused API account creation (CREATION_DENIED_INELIGIBLE_MCC); 2,500/wk cap; frequency quota Phase-0 MCC eligibility gate; seed spend/history; handle error codes — see account-creation limits & B11
23 TikTok BC advertiser-account cap Default per-BC advertiser limit varies by BC type — can block new tenants Confirm headroom Phase 0; raise via TikTok account manager (relationship-gated) — see TikTok structure
24 Meta CPAS (Collaborative Ads) Marketplace segment share + brand accept; Trendyol/HB API vs manual unknown Phase 2 core track — clarify before build (meta-collaborative-ads-cpas.md)

When onboarding or connector health checks detect:

Condition Action
Required scope not granted on OAuth re-consent Block platform mutations; System Ops alert
Developer token tier < Basic Block prod Google mutations
Meta app tier = Limited and tenant count > pilot Warn + throttle optimization
TikTok app not Live Block TikTok connector; show SKU caveat
DV360 API 403 / no contract Hide DV360 from plan templates
Rate-limit errors > N/hour per tenant Auto-pause optimization for tenant; ops alert

Emit platform.access.red_flag on event bus → System Ops + engineering ticket.


Doc Focus
Onboarding API cross-check Every onboarding step → API endpoint or UI-only gap
Google Ads Account model, agent scope
Meta Ads BM, system user, CAPI
TikTok Ads BC, Events API
DV360 IO, GMP
GA4 source of truth Measurement
Onboarding Provisioning order
Security & governance Secrets, RBAC
Roadmap Phase gates
System Ops Dashboard Quota / log visibility

Official references (verify periodically)