executionType: MANAGED_SALES_AGENT). That
connection needs read and trafficking access to your ad server. This page explains
what Interchange does with that access, what to grant for each supported ad server,
and why the grant stays narrow.
For the step-by-step setup, see
Storefront onboarding;
to compare an ad server against the other source families, see
Choosing a source.
Why does Interchange need access?
Buyers transact against your storefront, not against your ad server directly. Your storefront is the sales agent buyers reach; your Merchandising Agent answers their briefs. For that to work over your existing ad-server inventory, Interchange manages the AdCP sales-agent plumbing in front of your ad server, and that plumbing has to talk to it on your behalf. Without access, Interchange has nothing to discover, sell, or report against — your inventory stays invisible to buyers.What does Interchange do with your ad server?
With access granted, Interchange operates against it in three ways, the same across every supported ad server:- Reads your inventory. It syncs your existing ad units, placements, and products so your Merchandising Agent can compose buyer-facing products from what you already run. You do not re-key inventory into Interchange.
- Traffics campaigns. When a buyer transacts against your storefront, Interchange creates and manages the corresponding orders and line items in your ad server under the advertiser you route the buyer to. See Buyer routing. What actually reaches your ad server is governed by your approval settings — you can require human review of every media buy and creative before anything serves (the default, and the lowest-risk posture). See Reviewing buyer transactions.
- Reads delivery back. It reads impressions, spend, and pacing so delivery and reporting roll up to the buyer.
What access do I grant?
The grant differs by ad server, but the principle is the same: the least privilege that can read inventory and traffic campaigns, nothing more.Ad server (connectionType) | What you provide | How it’s used |
|---|---|---|
Google Ad Manager (google_ad_manager) | Your numeric network code. Scope3 provisions a per-customer service account and returns its email; you add that email as a user in your GAM network with a trafficking role. You never paste a password or token. | The service account reads inventory and traffics under the role you grant. You control and revoke it from your own GAM admin console. |
FreeWheel (freewheel) | Grant Scope3 access to your account in the FreeWheel partner portal and let us know once it’s live — Scope3 then picks up the partner API credentials there and provisions the source. You don’t paste a login password or personal API token. (Direct alternatives: a Publisher API client ID + client secret, a legacy username + password, or a 7-day temporary key for testing.) | The partner credentials Scope3 retrieves are forwarded to the managed ad-server source at provision time and never persisted by Scope3; they mint and auto-refresh short-lived tokens. |
SpringServe (springserve) | A login email + password, or a pre-minted API token. | Forwarded to the managed ad-server source at provision time and never persisted by Scope3; the source mints a fresh 2-hour token from the email/password and auto-refreshes it. |
Google Ad Manager — a least-privilege service account
With GAM you never share a login password or API token — Scope3 provisions a per-customer service account, and you grant its email a role. Grant the service-account email the least-privilege role that can read inventory and traffic campaigns —Trafficker, or a custom role with the equivalent API
permissions. That is the whole grant:
| Interchange needs | Interchange does not need |
|---|---|
| Read ad units, placements, and products | Network or account administration |
| Create and manage orders and line items | Manage GAM users or roles |
| Read delivery and pacing reporting | Change network or billing settings |
Keep the exact GAM menu wording anchored to Google’s own support documentation —
their console labels change. What Interchange owns is the contract above: the
service-account email it returns, and the read-plus-traffic role it needs.
FreeWheel and SpringServe — forwarded, never stored
FreeWheel connects through Scope3’s partner program: you grant Scope3 access in the FreeWheel partner portal and tell us when it’s live, and Scope3 picks up the partner API credentials there — you don’t hand over a login password or personal API token. SpringServe uses your account login or a token. Two properties hold for both:- Prefer the auto-refreshing grant. FreeWheel’s client ID + secret and SpringServe’s email + password each mint short-lived tokens that refresh themselves, so the connection keeps working without you re-entering anything. The pre-minted token paths (FreeWheel’s 7-day key, SpringServe’s API token) are for testing — they expire and don’t refresh.
- Scope3 never persists them. The credentials are forwarded to the managed ad-server source at provision time and are not stored by Scope3. Where a secret is held at all (see below), it’s encrypted and never returned.
How your credentials are handled
- Encrypted, never echoed. Any stored inventory-source credential (API key,
username/password, JWT key) is encrypted at rest and referenced only by an opaque
auth_secret_ref. API responses surfaceauthConfigured: true, never the secret itself. - No shared admin login. GAM is a scoped service account you grant and revoke yourself; FreeWheel/SpringServe use API credentials that mint short-lived tokens — not a human admin seat.
- You stay in control. Remove the GAM service-account user, or rotate the FreeWheel/SpringServe credential, and Interchange’s access stops.
- Nothing to re-key. Interchange reads your existing inventory directly, so your storefront sells what you already run.
Verifying the connection
After you grant access, Interchange provisions the source and probes the connection. Common failures right after setup:| Error code | What it means | What to do |
|---|---|---|
ADAPTER_PERMISSION_DENIED | The credential or grant is missing or hasn’t propagated — a GAM service-account email not yet added, or FreeWheel/SpringServe credentials rejected | Confirm the GAM email was added with a trafficking role, or re-check the FreeWheel/SpringServe credentials; wait a minute or two and retry |
ADAPTER_NETWORK_NOT_FOUND | The GAM network code is wrong | Re-check the numeric network code from your GAM network settings |
provisioningStatus and the
most recent lastErrorCode — with
Get ad-server connection,
and re-probe upstream reachability with
Test connection.
Related
Choosing a source
Ad server vs sales agent vs linked vs modular
Connect an ad server
Step-by-step setup for each ad server
Replace ad-server config
Set the network code or credentials on the source
Buyer routing
How buyers resolve to an advertiser