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

# Replace ad-server config

> Set the ad-server configuration on an ad-server-backed inventory source

`PUT /api/v2/storefront/inventory-sources/{sourceId}/ad-server`

Sets the ad-server configuration on an ad-server-backed source. The body fully replaces the config for the source's existing adapter (PUT semantics); it cannot change the adapter type on a live managed source. Create a new source to move between GAM, FreeWheel, SpringServe, or AdsWizz. `PATCH /api/v2/storefront/inventory-sources/{sourceId}/ad-server` is accepted as an alias with the same body and response, for clients migrating from the legacy `/esa/ad-server` route.

## Request

<CodeGroup>
  ```bash Google Ad Manager theme={null}
  curl -X PUT https://api.apostra.com/api/v2/storefront/inventory-sources/retail-gam/ad-server \
    -H "Authorization: Bearer $SCOPE3_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "google_ad_manager",
      "networkCode": "12345678",
      "connectionContract": {
        "id": "google-ad-manager",
        "version": 1,
        "authenticationMethod": "platform_service_account"
      }
    }'
  ```

  ```json FreeWheel theme={null}
  {
    "type": "freewheel",
    "clientId": "fw-client-id",
    "clientSecret": "<FREEWHEEL_CLIENT_SECRET>",
    "environment": "production",
    "defaultAdvertiserId": "adv_88421",
    "connectionContract": {
      "id": "freewheel",
      "version": 1,
      "authenticationMethod": "oauth2"
    }
  }
  ```

  ```json SpringServe theme={null}
  {
    "type": "springserve",
    "email": "ops@retail-network.example.com",
    "password": "<SPRINGSERVE_PASSWORD>",
    "environment": "production",
    "defaultDemandPartnerId": 50231
  }
  ```
</CodeGroup>

## Parameters

| Field      | Type          | Required | Notes                                                                                                        |
| ---------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `sourceId` | string (path) | Yes      | Storefront-scoped inventory source ID                                                                        |
| `type`     | enum          | Yes      | Existing source adapter: `google_ad_manager`, `freewheel`, or `springserve`. Must match the connected tenant |

**`google_ad_manager`**

| Field                | Type   | Required | Notes                                                                                                                                                        |
| -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `networkCode`        | string | Yes      | Numeric GAM network code (1–32 digits). Apostra manages the service-account credentials                                                                      |
| `connectionContract` | object | No       | Exact selector for new clients: `google-ad-manager`, version `1`, authentication method `platform_service_account`. Omission preserves the legacy setup path |

**`freewheel`**

| Field                 | Type   | Required    | Notes                                                                                                                                                                           |
| --------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId`            | string | Conditional | FreeWheel Publisher API client ID. Required with `clientSecret`; omit when using `apiToken`                                                                                     |
| `clientSecret`        | string | Conditional | FreeWheel Publisher API client secret. Required with `clientId`. Write-only — never returned or written to Apostra connection row; encrypted by the managed source              |
| `username`            | string | Conditional | Legacy FreeWheel username for password-grant authentication. Prefer `clientId` + `clientSecret`                                                                                 |
| `password`            | string | Conditional | Legacy FreeWheel password for password-grant authentication. Write-only — never returned or written to Apostra connection row; encrypted by the managed source                  |
| `apiToken`            | string | Conditional | Pre-minted token; used only when no client ID/client secret is supplied. Testing only                                                                                           |
| `environment`         | enum   | No          | `production` (default), `staging`, or `sandbox` for testing                                                                                                                     |
| `defaultAdvertiserId` | string | No          | Default FreeWheel advertiser id (max 64)                                                                                                                                        |
| `connectionContract`  | object | No          | Exact selector for new client-credential setup: `freewheel`, version `1`, authentication method `oauth2`. Pre-minted tokens use `bearer_token`; omission preserves legacy setup |

**`springserve`**

| Field                    | Type    | Required    | Notes                                                                            |
| ------------------------ | ------- | ----------- | -------------------------------------------------------------------------------- |
| `email`                  | string  | Conditional | Required for password grant; omit when using `apiToken`                          |
| `password`               | string  | Conditional | Required for password grant. Write-only — never returned or persisted by Apostra |
| `apiToken`               | string  | Conditional | Pre-minted token; used only when no email/password. Testing only                 |
| `environment`            | enum    | No          | `production` (only supported value)                                              |
| `defaultDemandPartnerId` | integer | No          | Default SpringServe demand partner id                                            |

<Warning>
  FreeWheel and SpringServe credentials are forwarded to the managed ad-server source and encrypted there. They are **never written to Apostra connection row** — that row stores only non-secret display fields (client ID/login, environment, default advertiser/demand-partner id). For FreeWheel production setup, prefer client ID/client secret (the managed source mints and auto-refreshes short-lived tokens); reserve pre-minted `apiToken` for testing.
</Warning>

## Response

`200 OK` with the updated `EsaConnection` (see [Get ad-server connection](/v2/storefront/inventory-sources/tasks/get-ad-server-connection) for the full shape):

```json theme={null}
{
  "id": "550199",
  "customerId": 4210,
  "tenantId": "tnt_retail_gam",
  "adServer": { "type": "google_ad_manager", "networkCode": "12345678" },
  "serviceAccountEmail": "retail-gam-4210@scope3-esa.iam.gserviceaccount.com",
  "lastError": null,
  "lastErrorCode": null,
  "updatedAt": "2026-05-02T09:14:00Z"
}
```

For Google Ad Manager, `serviceAccountEmail` is the address the publisher must grant access to in their GAM admin console before provisioning succeeds.

## Errors

* `400 VALIDATION_ERROR` — unknown or mismatched `type`, missing credentials for the chosen adapter, or malformed `networkCode`.
* `401 UNAUTHORIZED` — missing or invalid API key.
* `404 NOT_FOUND` — no ad-server-backed source with this `sourceId`.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Inventory source tasks" href="/v2/storefront/inventory-sources/tasks" icon="list-check">
    All operations
  </Card>

  <Card title="Rotate credentials" href="/v2/storefront/inventory-sources/tasks/rotate-credentials" icon="key">
    In-place credential rotation
  </Card>

  <Card title="Test connection" href="/v2/storefront/inventory-sources/tasks/test-connection" icon="plug-circle-check">
    Probe upstream reachability
  </Card>

  <Card title="Get ad-server connection" href="/v2/storefront/inventory-sources/tasks/get-ad-server-connection" icon="server">
    Connection state
  </Card>
</CardGroup>