> ## 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.

# Connecting an ad server

> How a seller account connects Google Ad Manager, FreeWheel, SpringServe, AdsWizz, Broadsign or Epsilon Retail Media as an inventory source through V3, and why credentials go through a form.

A seller account connects its ad server as an inventory source through V3. The supported ad servers are
Google Ad Manager, FreeWheel, SpringServe, AdsWizz, Broadsign and Epsilon Retail Media (CitrusAd). What
Broadsign asks for and does is described [below](https://docs.apostra.com/v3/seller-connect-ad-server.md#broadsign). The Google Ad
Manager role and permissions Apostra needs, and what each one is for, are described in
[Google Ad Manager access](https://docs.apostra.com/v3/seller-gam-access.md). What FreeWheel, SpringServe and AdsWizz ask for is
described in [Ad server access](https://docs.apostra.com/v2/storefront/inventory-sources/ad-server-access.md).

## Start from an agent

An agent starts a connection with `save_inventory_source` and only `adServer`:

```json theme={null}
{ "adServer": { "type": "freewheel" } }
```

`type` is `google_ad_manager`, `freewheel`, `springserve`, `adswizz`, `broadsign` or `citrusad`. The call creates nothing.
It returns `action: "ad_server_form"` and opens the **Connect ad server** form, where the seller enters the
ad server's details and credentials. Credentials are never passed in an agent's tool call, so they never
pass through chat. Sending `adServer` with any other field is refused with `VALIDATION_FAILED`.

For Google Ad Manager the result also carries `serviceAccountEmail`. Apostra signs in to GAM with a service
account it creates for your organization, and you add that email as a user in your GAM network before
connecting. The first call creates the service account; later calls return the same one. An agent can tell
the seller which email to add without opening the form.

`open_page({ "page": "connect_ad_server" })` opens the same form without choosing an ad server first.

## Choose an inventory source

Call `get({ "kind": "source_options" })` in a seller account to read the available ad servers and partner sales agents. `object.options` gives each option's label, summary, connection action, certification and known limits. A partner agent appears when its owner can serve other sellers and has published its connection contract. Selecting a partner opens its connection form, which asks for the details the partner requires.

## What the form does

The form sends the ad server's configuration and credentials to Apostra, which forwards the credentials
to the managed source and never stores them on the Apostra connection or returns them.

On an existing source, the ad-server source page sends the replacement configuration the same way.
Google Ad Manager's network settings are replaced in place. For the other ad servers the credentials are
rotated in place, so the source keeps its products and sync history.

A credential save always sends the secret that signs in to the ad server. Any other secret already on
file that the save leaves out is kept, so you do not have to enter it again. Settings that go with a kept secret, such as the Broadsign Control domain id, are kept
too when the save does not send them. To remove a secret on purpose, name it in `removeSecrets`. The
secret that signs in to the ad server cannot be removed; deactivate the source instead.

A source you deactivated, or that Apostra deactivated after a sync error, is disabled: it no longer
syncs and buyers cannot book it. To bring it back, connect the same ad-server account again. For Google
Ad Manager, connect the same network code. The disabled source is switched back on in place, so it keeps
its products, pricing and approvals. It does not create a second source. A disabled source cannot be
switched back on directly when Apostra holds no record of the managed principal it acts as; connecting the
account again supplies it.

When the managed source refuses a credential save, nothing on the source changes and the form shows why:

* A save it cannot accept, for example one that changes the sign-in email without sending the password
  again, or that names a secret the ad server does not have, is refused with a message saying what to send.
* If the secrets on file can no longer be read, the save is refused and asks you to enter every secret for
  the connection again.
* If another save changed the connection's secrets while this one was being checked, the save is refused
  with a conflict. Send it again.

Epsilon Retail Media connects in two steps: the form creates the source, then stores its API key. If
storing the key fails, the form retries against the source it already created instead of creating a
second one.

These form writes are page-only. They are not part of an agent's tool list, the public V3 HTTP API or the
SDKs.

## Broadsign

Broadsign sells digital out-of-home screen time. Apostra connects to **Broadsign Guaranteed Campaigns**
(Broadsign Direct), the system that books screen time.

**What you provide.**

* A production Broadsign Guaranteed Campaigns login email and password. The user must be active and allowed
  to read screens and to create and book proposals.
* The three-letter currency your Broadsign domain prices in.

Broadsign does not report a currency through its API, so the currency you enter is the currency every
booking uses. It must match your storefront's settlement currency before a booking can become ready.

**What Apostra keeps.** Every Broadsign connection pins the `broadsign:v1` connection contract, which fixes the production
Direct API and an email and password login. The password is forwarded to the managed source and never
stored on or returned by the Apostra connection. Only the email, the production environment, the domain
currency and the contract stay on the connection.

**What the connection does.**

* Reads your domain's screens.
* Books one Broadsign proposal per media buy, with one line item per package.
* Reads each buy's status and its flight-to-date delivery: delivered impressions from the line items, and
  spend as those impressions at the booked CPM.
* Sends flight date changes to Broadsign as amendments.
* Cancels.
* With [Broadsign Control access](https://docs.apostra.com/v3/seller-connect-ad-server.md#optional-broadsign-control-access): sends creative to
  your screens, pauses and resumes a buy, and reads daily plays and impressions from proof-of-play.

Budget and impression changes are refused. Without Control access, assigning a creative to a buy is refused,
pausing and resuming are refused, delivery stays at flight-to-date totals, and you schedule creative in Broadsign
yourself.

> [!NOTE]
>
> Apostra has not yet run this connection, with or without Control access, against a live Broadsign account. It
> was built from Broadsign's published API descriptions, so expect adjustments when the first one connects.

If Broadsign rejects the login, the connection reports `ADAPTER_INVALID_CREDENTIALS` or
`ADAPTER_PERMISSION_DENIED`. Check the email and password and the user's permissions, then save them again on
the ad-server source page.

### Optional Broadsign Control access

Broadsign Control is the separate Broadsign API for creative content and proof-of-play. Adding it is optional;
you can connect Broadsign Guaranteed Campaigns without it. With it, Apostra can do three more things:

* **Send creative to your screens.** Apostra checks the asset, uploads it to Control from its URL, adds it to the
  booked campaign's schedule, and reads the schedule back to confirm it is there. The asset must be a hosted image
  or video at a public https URL, with no third-party trackers. Once Apostra has your screens, its width and
  height must equal the resolution of every screen in the package. Duration is not checked, and companion banners,
  placement routing and weights are not supported. If Broadsign has not created the Control campaign yet, the
  creative stays uploaded and Apostra attaches it once the campaign exists.
* **Pause and resume a buy.** Apostra sets the campaign inactive or active in Control and reports success only
  when Control shows it. Broadsign Direct has no pause, so without Control a pause is refused.
* **Report what actually played.** Apostra reads daily plays and impressions from Control's proof-of-play, and
  shows spend as those impressions at the booked CPM. A report can cover any day in the 90 days before the last
  read. Apostra's own delivery totals cover impressions, spend, clicks and completed views, and do not store play
  counts yet.

When you add Control access, the connection test also checks it, and a Control failure fails the whole test.
Apostra signs in to Control with the token only. Broadsign recommends client certificates in production, which
Apostra does not support.

To add it, enter two values together, or neither:

* **Control API token:** a Broadsign Control REST API token. It is write-only: forwarded to the managed
  source and encrypted there, never stored on the Apostra connection or returned.
* **Control domain id:** the numeric id of the Broadsign Control domain that holds your screens. It is
  stored and returned as `controlDomainId` on V3 reads of the connection
  (`include: ["adServerConnection"]`), so you can see Control is set up.

Control access uses the `broadsign:v2` connection contract. A save that sends the Control values with
`broadsign:v1`, or sends the token without the domain id, is refused. A save that sends only the domain id
keeps the token already on file, and is refused when there is none.

To get a token, ask Broadsign Services to enable REST API access for an API user on your Control domain. A
Control administrator then generates the token in Broadsign Control Administrator, under the user's
properties, in **Credentials**. Treat it like a password. To replace it, save a new token and the domain id
on the ad-server source page.

The token is never shown again, and you do not need to enter it again: leave the token field blank when
you change your other Broadsign credentials, and the token on file is kept. Through the API, a save that
leaves the token out keeps it, along with the stored domain id when the save does not send one. To remove
Control, clear both Control fields on the ad-server source page, which says that saving removes Control
access. Through the API, name it in `removeSecrets: ["control_api_token"]`, so Control is never removed by
accident.

## After connecting

The new source appears in `search({ "kind": "inventory_source" })`. Read its connection state and setup
progress with `get({ "kind": "inventory_source", "id": "SOURCE_ID" })`. See
[Reading an inventory source](https://docs.apostra.com/v3/seller-inventory-source-facts.md) for what that read returns.

To see which of a managed source's secrets are on file, add `include: ["adServerConnection"]`. Alongside
the connection, the read returns `contract`, the connection contract the source is pinned to, and
`secrets`, each declared secret as `{ "key", "label", "onFile" }`. It never returns a secret's value.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.