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

# Google Ad Manager access Apostra needs

> The Google Ad Manager role and permissions the service account Apostra signs in with needs, what each one is used for, what stops working without it, and what it costs to grant less.

When you connect Google Ad Manager (GAM), Apostra runs a sales agent in front of your network for you. It
signs in to GAM as a service account that Apostra creates for your organization, and you give that service
account a role in your network. This page says what the role must allow, what Apostra uses each permission
for, what stops working without it, and what you give up if you grant less.

To get the service account's email and connect the network, see
[Connecting an ad server](https://docs.apostra.com/v3/seller-connect-ad-server.md).

## The short answer

Apostra recommends the built-in **Administrator** role. That is a recommendation, not a check. Apostra
works with any role that can do everything in the list below, and GAM does not tell Apostra what a custom
role allows.

A custom role works if it lets the service account:

* read ad units, placements, labels and audience segments;
* read, create, edit and archive orders and line items, and pause, resume and release line items;
* approve orders, and approve orders that overbook if you sell guaranteed inventory;
* create creatives and attach them to line items;
* read custom targeting keys and values, and add values to free-form keys;
* read advertisers, and create them if you want Apostra to create advertisers for you;
* run reports and read forecasts.

The service account must also be able to see your advertisers. If your network uses teams, add it to a
team that includes them, or to a team with **All entities**.

Do not use the built-in **Trafficker** role: it cannot approve orders. Neither can **Salesperson**,
**Executive**, **Advertiser**, **Legal manager** or **Ad Exchange manager**.

Apostra never needs to manage your GAM users, roles or teams, change your network or billing settings, or
create or change your ad units and placements.

## Adding the service account

You add a service account in GAM through **API access** in your network's global settings, with
**Add a service account user**. API access must be turned on. Do not add it as a new user on the Users
page: that sends an email invitation, and a service account has no inbox to accept it. Once it is added,
the service account's email appears in your users list as an active user. GAM's menu names change, so
follow Google's own help for the exact path.

The person who adds the service account needs rights in GAM to add users and assign roles. You can
remove the service account at any time, and Apostra's access stops.

## What each permission is for

| Access | What Apostra uses it for | Without it |
| - | - | - |
| Read ad units and placements | Syncs your inventory, so you build products from what you already run. Labels and audience segments are read in the same sync. | Apostra has no inventory to build products from. Apostra reports that the role cannot view ad units. |
| Read orders and line items | Reads the orders it created: their status, and the delivery counts GAM keeps on each line item. | Apostra cannot see what happened to a buy after booking it. Apostra reports that the role cannot view orders and line items. |
| Create and edit orders and line items | Books each media buy as an order with its line items. Applies changes to a live buy, such as new dates or budget. Writes the ad units to leave out when it optimizes where a buy delivers. | Buys cannot be booked or changed, and Apostra does not optimize placement. |
| Pause, resume, release and archive line items | Pauses and resumes a buy. Releases or archives its line items when the buy is cancelled. | A buyer's pause, resume or cancel cannot reach GAM. |
| Approve orders | Approves each order once its line items and creatives are in place. See [Order approval](https://docs.apostra.com/v3/seller-gam-access.md#order-approval). | Every order stays in draft in GAM until someone approves it there. A new listing on Apostra is refused. |
| Approve orders that overbook | Approves an order that asks for more than GAM forecasts. Apostra asks for this when a buy may overbook, and falls back to a plain approval if GAM refuses. | GAM refuses to approve an order that exceeds its forecast, and the order stays in draft. |
| Archive orders | Archives the draft order when a booking fails after the order was created. | The draft order stays in your network, and you archive it yourself. |
| Create creatives and attach them to line items | Uploads the buyer's creatives and attaches them to the right line items. | The buy's creatives cannot reach GAM, so its line items have nothing to serve. |
| Read custom targeting keys and values | Targets line items with your key-values. | Products and buys cannot target key-values. |
| Add values to free-form keys | Adds a value when a buy targets one that a free-form key does not have yet. Predefined keys only match the values they already have. | A buy that needs a new value on a free-form key cannot be booked. |
| Read advertisers | Lists your GAM advertisers, so you can choose a default advertiser and map each buyer to an advertiser. | You cannot choose advertisers in Apostra. |
| Create advertisers | Creates an advertiser when you ask for one on the ad-server source page, and creates the default and sandbox advertisers it books on. | Apostra uses an existing advertiser with the exact same name if there is one. Otherwise, create the advertiser in GAM yourself and choose it. |
| Run reports | Reads delivery for buyers and billing, prices products from your delivery history, and finds where to optimize placement. | See [Reporting access](https://docs.apostra.com/v3/seller-gam-access.md#reporting-access). |
| Read forecasts | Checks availability for guaranteed buys. | Apostra cannot confirm availability. If you hold over-forecast buys for review, those buys are held. See [Guaranteed buys over the ad server forecast](https://docs.apostra.com/v3/seller-guaranteed-availability.md). |
| See advertisers through a team | Required for every advertiser read when your network uses teams. | GAM returns no advertisers. See [Advertiser team access](https://docs.apostra.com/v3/seller-gam-access.md#advertiser-team-access). |

Apostra also reads your network's time zone and currency, and the service account's own GAM user and
role.

## Checks Apostra runs

GAM tells Apostra the service account's role name, but not what a role allows. So Apostra learns about a
missing permission in two ways: from a small read that needs it, or from GAM refusing a real action.

### Order approval

Apostra approves each order once its line items and creatives are in place. When GAM refuses, the order
stays in draft and the buy waits. It does not deliver until the order is approved.

Apostra finds this before the first buy if the service account has one of the six built-in roles that
cannot approve orders. It reads the role when you connect and each time you run **Test connection** on
the ad-server source page. A custom role cannot be judged from its name, so Apostra finds a custom role
that cannot approve the first time GAM refuses an approval.

While the problem stands:

* your setup checklist shows **Ad-server order approval**, and the source's diagnostics name your GAM
  network;
* held buys show on your Media Buys list as **Held in your ad server**, because its user can't approve
  orders;
* a new listing on Apostra is refused, with the fix. Existing listings stay listed, and you can always
  unlist them.

Three things cause it: the role cannot approve orders, the role can approve but not overbook and the
order exceeds the forecast, or your network routes orders through an approval workflow that does not
include the service account. To fix it, give the service account the Administrator role or a custom role
that can approve orders (and overbook, if you sell guaranteed inventory), or add it as an approver in your
order approval workflow. Until then, you can approve each held order in GAM yourself, and the buy moves
on once GAM shows the order approved.

If the warning came from the role name, run **Test connection** after changing the role. If it came from
a refused approval, it clears the next time GAM accepts an approval from the service account.

Approving orders in GAM is separate from your own review of buyers' media buys and creatives in Apostra.
Changing one does not change the other.

### Reporting access

Apostra checks reporting access by running a one-day report about once a day. If GAM refuses, the
source's diagnostics show that reporting access is missing and when it was last checked.

Without reporting access:

* delivery reports for buys on this source are incomplete;
* Apostra cannot price products from your delivery history, so you keep prices current yourself with a
  wholesale pricing feed or fixed prices;
* Apostra does not optimize placement, and delivery goals are yours to manage.

Inventory, orders and selling are not affected today. Apostra has decided that a seller on a source it
manages will need its delivery to reach Apostra automatically before it can sell, either through GAM
reports or through a reporting connection the seller provides. That is not enforced yet.

To fix it, give the service account's role permission to run reports. The next daily check picks it up.
To resume reporting at once, choose **Access confirmed - re-check reporting** on the diagnosis.

### Advertiser team access

GAM shows a user only the advertisers on its teams. A service account that authenticates but is on no
team with advertisers sees an empty advertiser list, which looks the same as a network with no
advertisers.

When GAM returns no advertisers and your network uses teams, Apostra checks the service account's teams.
If none of them gives it access to all advertisers, the advertiser sync fails and the source shows an
access problem to fix in GAM. Apostra keeps the advertiser list it had, rather than treating your
advertisers as gone.

To fix it, add the service account to a team that includes your advertisers, or to a team with
**All entities**, then refresh the source.

## Granting less than Administrator

You can grant less. Each permission you leave out has a cost, in the table above. In short:

| If the service account's role | What it costs you |
| - | - |
| Is a custom role that covers the list above | Nothing, once the role is right. Apostra cannot check a custom role in advance, so a missing permission shows up the first time GAM refuses. |
| Cannot approve orders | You approve every order in GAM yourself, and new listings on Apostra are refused until you grant it. |
| Cannot approve orders that overbook | Guaranteed orders that exceed the forecast wait in draft for you. |
| Cannot archive orders | You clean up the draft orders that failed bookings leave behind. |
| Cannot create advertisers | You create advertisers in GAM yourself. |
| Cannot run reports | Incomplete delivery reports for your buyers, prices you keep current yourself, and no placement optimization. |
| Sees only some advertisers, through its teams | Apostra sees, and can book on, only those advertisers. |

You cannot leave out reading inventory, reading and writing orders and line items, creatives, or reading
custom targeting. Without them, Apostra cannot book a buy.

## Related

> [card] [Connecting an ad server](https://docs.apostra.com/v3/seller-connect-ad-server.md)
>
> Get the service account email and connect your network

> [card] [Your first booking](https://docs.apostra.com/v3/seller-first-booking.md)
>
> The full path from setup to a buyer's first booking

> [card] [Source diagnostics](https://docs.apostra.com/v3/seller-source-diagnostics-page.md)
>
> Where access problems on a source show up

> [card] [Guaranteed buys over the ad server forecast](https://docs.apostra.com/v3/seller-guaranteed-availability.md)
>
> What happens when GAM cannot confirm availability


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