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 do the work your source needs, nothing more.

​

Google Ad Manager — service-account permissions

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. The service-account email must be able to read inventory, traffic orders and line items, and approve orders. We recommend the Administrator role. You can instead give it a custom role with trafficking and order approval, or add it as an order approver in GAM’s order approval workflow. Do not use the built-in Trafficker role: it cannot approve orders. The following built-in GAM roles cannot approve orders: Trafficker, Salesperson, Executive, Advertiser, Legal manager, and Ad Exchange manager. GAM does not expose custom-role permissions to Apostra, so a custom role is checked when GAM first refuses an approval.

​

What happens when the GAM user cannot approve orders

Apostra flags this in Seller Setup before listing, either from a refused approval or, where the managed sales agent supports it, a built-in role check. A new listing on Apostra is refused with the fix until the permission is corrected. Existing listings stay listed, and you can always unlist them.

​

Fix GAM order approval

1. In GAM, change the service-account user’s role to Administrator, or give it a custom role with trafficking and order approval.
2. If your network uses an order approval workflow, add the service-account user as an order approver.
3. Re-run the connection check in Seller Setup.

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, stops using the denied capability in its regular syncs, and checks it again about once a day, so a grant is picked up within a day even if nobody re-checks. Once FreeWheel confirms the grant, use the diagnosis’s Access confirmed - re-check action for reporting or forecasting to resume at once; 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. The Seller Source diagnostics page in chat shows the current connection state, the most recent error code, and lets you re-probe upstream reachability. See Source diagnostics.

​

Related