> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Why Apostra needs access to your ad server
> What Apostra does with Google Ad Manager, FreeWheel, SpringServe, and AdsWizz, the access each one asks for, and why the grant stays narrow.
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](/v2/setup/storefront-onboarding#connect-inventory-sources);
to compare an ad server against the other source families, see
[Choosing a source](/v2/storefront/inventory-sources/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](/v2/storefront/buyer-routing/overview). 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](/v2/storefront/approvals/overview).
* **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.
| Ad server | Provider field | Apostra metric | Current boundary |
| ----------------- | ----------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Google Ad Manager | Ad-server impressions | Impressions | Daily and package totals |
| Google Ad Manager | CPM/CPC revenue | Spend | Network currency |
| Google Ad Manager | Ad-server clicks | Clicks | Daily and package totals |
| Google Ad Manager | VAST video completions | Completed views | In-stream only; outstream does not fire VAST completion events |
| Google Ad Manager | Active View viewable + measurable impressions | Viewability evidence | Reported only when Active View measured the inventory |
| FreeWheel | Nightly forecast delivered impressions | Impressions | Lifetime cumulative snapshot, not an arbitrary requested date range |
| FreeWheel | Nightly forecast delivered budget | Spend | No clicks or completion counts on this reporting path |
| SpringServe | Impressions / cost / clicks / fourth quartile | Impressions / spend / clicks / completed views | Latest reporting-sync window; arbitrary date ranges are not yet available |
| AdsWizz | Impressions / spend / clicks / completion count | Impressions / spend / clicks / completed views | Daily cached delivery; audio-specific and conversion fields are not exposed as standard metrics |
Google Ad Manager, FreeWheel, SpringServe, and AdsWizz run in the managed
ad-server source. Their product declarations must not claim metrics beyond
the rows above, and access to a provider's reporting API can narrow what is
returned for a specific connection.
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.**
| Ad server (`connectionType`) | What you provide | How it's used |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Google Ad Manager** (`google_ad_manager`) | Your numeric **network code**. Apostra provisions a **dedicated service account for your organization** 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`) | For self-service setup, a Publisher API **client ID + client secret**. An assisted FreeWheel partner-portal grant can still be provisioned separately; a legacy **username + password** or 7-day temporary key remains available for compatibility/testing. | The credential is forwarded to the managed ad-server source and encrypted there; only non-secret display configuration and the versioned contract selection stay on your Apostra connection. Client credentials 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 and encrypted there; only non-secret display configuration and the versioned contract selection stay on your Apostra connection. The source mints a fresh 2-hour token from the email/password and auto-refreshes it. |
| **AdsWizz** (`adswizz`) | A static **API key**, numeric agency id, and agency billing currency. | New setup pins `adswizz:v1`, including the fixed Domain and Forecasting endpoints and `x-api-key` authentication. The key is forwarded to and encrypted by the managed source; only non-secret agency configuration and the contract selection stay on Apostra connection. |
### 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:
| Apostra needs | Apostra 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 |
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.
Keep the exact GAM menu wording anchored to Google's own support documentation —
their console labels change. What Apostra 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 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.
| 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 |
You can read the current connection state — including the enabled/disabled
state (`deactivatedAt`) and the most recent `lastErrorCode` — with
[Get ad-server connection](/v2/storefront/inventory-sources/tasks/get-ad-server-connection),
and re-probe upstream reachability with
[Test connection](/v2/storefront/inventory-sources/tasks/test-connection).
## Related
Ad server vs sales agent vs linked vs modular
Step-by-step setup for each ad server
Set the network code or credentials on the source
How buyers resolve to an advertiser