Why Apostra needs access to your ad server

If you sell through an ad server, you connect it to Apostra as an ad-server-backed source (executionType: MANAGED_SALES_AGENT). That connection needs read and trafficking access to your ad server. This page explains what Apostra 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 Apostra 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, Apostra 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, Apostra has nothing to discover, sell, or report against — your inventory stays invisible to buyers.

​

What does Apostra do with your ad server?

With access granted, Apostra 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 Apostra.
• Traffics campaigns. When a buyer transacts against your storefront, Apostra 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.

​

Reporting metric mapping

The managed source returns only metrics its ad server actually measured. Rates such as CTR and completion rate are calculated from the raw counts; a missing metric is not turned into zero. Apostra does not change your ad-server settings, manage your users, or touch inventory you do not sell through your storefront.

​

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.

​

Google Ad Manager — a least-privilege service account

With GAM you never share a login password or API token — Apostra provisions a service account dedicated to your organization, and you grant its email a role. New GAM setup requests pin the platform-owned, versioned google-ad-manager:v1 connection contract. The contract declares the numeric network code and platform service-account authentication; it contains no secret value and no Partner identity. 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 base grant: Automatic GAM order approval is a separate permission from creating orders and line items. If you want Apostra to approve eligible orders automatically, the service account may also need your network’s approval/overbook grant. GAM configuration varies, so Apostra does not claim this permission is present during connection setup or create a real order merely to probe it. When a live order needs external approval, Apostra creates an action item; approve the order in GAM, and status polling completes the item after the order becomes active. This does not change your storefront’s own media-buy and creative review settings.

​

FreeWheel and SpringServe — forwarded, never stored on the connection row

FreeWheel’s self-service form accepts a Publisher API client ID and client secret. An assisted partner-portal grant remains available outside that form. New self-service requests pin the built-in freewheel:v1 connection contract. It declares the fixed OAuth token endpoint, environment, optional default advertiser, and the selected OAuth2 client-credentials method; it contains no credential value and no Partner identity. New SpringServe requests pin the built-in springserve:v1 contract. It fixes the SpringServe API and authentication endpoints and declares either the email/password credential exchange or an API token sent in the Authorization header; the contract contains no credential value or Partner identity. FreeWheel may provision reporting and forecasting separately from the base API connection. If either capability is missing, ask your FreeWheel representative to enable it for the API user. Apostra records that state and stops calling the denied capability instead of retrying indefinitely. Once FreeWheel confirms the grant, use the diagnosis’s Access confirmed - re-check action for reporting or forecasting; a successful check resumes the paused capability without replacing credentials or reconnecting the source.

• 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.
• The connection row never stores them. The credentials are forwarded to the managed ad-server source and encrypted there. The local Apostra connection stores only non-secret display fields and the versioned contract selection; the secret is never returned.

​

How your credentials are handled

• Encrypted, never echoed. External-agent credentials are encrypted at rest and referenced by an opaque auth_secret_ref. Managed FreeWheel and SpringServe credentials are forwarded to the managed source and encrypted there; their local connection rows contain only non-secret display configuration. API responses never return 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 Apostra’s access stops.
• Nothing to re-key. Apostra reads your existing inventory directly, so your storefront sells what you already run.

​

Verifying the connection

After you grant access, Apostra provisions the source and probes the connection. For credential-backed adapters like FreeWheel and SpringServe, a failed credential probe stops setup before the source is accepted; re-check the credentials or grant, then submit again. Common failures right after setup: After a source is accepted, the source dashboard separates first-sync progress from action-required failures: a running initial inventory sync means the source is connected but not live yet, while adapter authentication or access failures mean the connection needs to be reconnected or reconfigured. You can read the current connection state — including the enabled/disabled state (deactivatedAt) and the most recent lastErrorCode — with Get ad-server connection, and re-probe upstream reachability with Test connection.

​

Related