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

# Run Apostra for several client accounts

> Choose an account shape, a billing route and a credential when one platform buys media for several clients, and limit what each client's work can do.

This page is for a platform or agency that buys media for several clients and
runs a server-side buyer agent to do it. It makes a recommendation for each
choice, and says plainly where Apostra does not do something yet.

| Choice | Recommendation |
| - | - |
| Account shape | One Buyer Account with an advertiser for each client. Give a client its own account when it needs its own sign-in or its own billing choice with a seller. |
| Billing route | Direct billing by the seller where the seller offers it, with each client's legal entity on its advertiser. Otherwise your organization is invoiced. |
| Credential | A user API key made by a dedicated service user. When clients need different limits, a buyer agent with one grant for each client's advertiser. |
| Limits per client | Read or read-and-write grants, a separate launch step your application controls, and the campaign budget. |

## Choose an account shape

An advertiser is one of your clients' brands. A Buyer Account holds advertisers,
and an organization holds Buyer Accounts. You can run several clients in one
Buyer Account, or give each client a child Buyer Account under your
organization.

| | One Buyer Account, many advertisers | A child Buyer Account for each client |
| - | - | - |
| Billing | One account, one billing policy for each seller. A media billing entity can still be attached to each advertiser. | Each account makes its own billing policy choice for each seller. IU plan and billing details stay with your organization. |
| Access | Your people and your credential see every advertiser in the account. You limit a buyer agent advertiser by advertiser. | Your organization's administrators reach every child account. A client's own members see only their account. |
| Isolation | Clients share one account, one operating unit and one set of seller connections. | Sellers see each account as its own operating unit of your organization. |
| Credentials | One credential can serve every client. | A credential reaches one account, so each client account needs its own. |
| Setup | `save_advertiser` for each client. | Each child needs `save_account`, which an organization administrator approves on the website. An organization can create 25 accounts in any 24 hours. |

No plan limits how many Buyer Accounts an organization holds. Archived accounts
keep their history. See
[Accounts in an organization](https://docs.apostra.com/v2/account-capacity).

**Recommendation.** If clients never sign in to Apostra and one agent does the
buying, start with one Buyer Account and an advertiser for each client. That is
the shape where one credential and per-client grants work today. Give a client
its own child account when its own people need to sign in, or when it needs a
different billing choice with a seller than your other clients.

An operator fee is set on a campaign. [Operator fees](https://docs.apostra.com/v3/operator-fees.md)
describes it for client accounts under your organization and lists the
conditions to meet before you use one.

## Choose a billing route

Media is billed by transaction, and the billing party decides who invoices it.
For each seller you choose between two routes.

**Your organization is invoiced.** A client account under your organization is
invoiced to your organization by default. You invoice your client yourself.
Apostra invoicing your client directly is not available yet. See
[Who pays whom](https://docs.apostra.com/v3/operator-fees.md#who-pays-whom).

**The seller invoices the business you name.** An administrator approves direct
billing for a seller. The seller then invoices the media billing entity
resolved for the advertiser, not you. Apostra looks for an entity attached to
the advertiser first, then to its account, then your organization's primary
entity. An advertiser with no resolved entity cannot open a directly billed
account with the seller, so attach each client's legal entity to its
advertiser first. The approval covers your Buyer Account and that seller, and
applies to every current and future advertiser in the account. See
[Approve direct billing](https://docs.apostra.com/v2/buyer/storefronts/tasks/accept-direct-billing.md) and
[Media billing entity configuration](https://docs.apostra.com/v2/buyer/billing/media-billing.md).
Choose the route for a seller with `save_connection` and its `billing` field.
Direct billing is not offered by every seller, and some platforms bill your
connected account directly with no choice.

**Consolidated media invoicing through Apostra is not fully live.** In
consolidated billing the seller sends its invoice to Apostra, not to you. The
setup that names the legal entity on that invoice is configuration and preview
only today. It does not yet change who an invoice is addressed to. Ask your
Apostra contact before you plan client media around it.

**Recommendation.** Use direct billing where the seller offers it and attach
each client's entity to its advertiser. That puts the media invoice with the
client's own business. Where it is not offered, your organization is invoiced
and you invoice the client.

Apostra's own charges are separate. They are billed to your organization on one
plan, whatever the number of accounts. See
[What you pay as a buyer](https://docs.apostra.com/v3/plan-and-billing.md#what-you-pay-as-a-buyer).

## Choose a credential

A credential reaches one account. This is true of a user API key, an
organization API key, an M2M application and a buyer agent. Sending
`X-SCOPE3-CUSTOMER-ID` with another account does not widen it: on the V3 HTTP
API the request is refused with `403`. To work for several clients with one
credential, hold the clients' advertisers in one account.

| Credential | What it reaches | Use it for |
| - | - | - |
| A user API key made by a dedicated service user | The account it was created in, with the owner's role. A read-only member's key cannot write. | A server-side agent for one account that needs no per-client limits. Create it in **Settings → API Access** while signed in as the service user. |
| An M2M application | One account, on the HTTP API only. MCP refuses it. | A deployed backend that needs OAuth client credentials. An organization administrator creates it. |
| A buyer agent | The advertisers an administrator grants it, each read or read and write, in the account it is registered in. | A server-side agent that needs a different limit for each client. |
| A person's OAuth connection | Every account that person can reach, named with `accountId` on each call. It acts as that person. | A person working with a coding agent. Not a server credential: a person approves it in a browser. |
| Agent Registration | A 30-day sandbox that cannot spend until claimed. | Trying Apostra. Not for running clients. |
| An identity-only credential issued from **Manage buyer agents** | Nothing. Every business API answers `403`. | Proving who an agent is. Register a credential that can call APIs instead. |

**Recommendation.** Start with a user API key made by a dedicated service user,
so the key does not depend on one person's job. It reaches every advertiser in
the account. When your clients need different limits, for example one client
read-only, use a buyer agent: an administrator grants it each client's
advertiser, and it reaches only the advertisers it is granted. Registering a
credential to a buyer agent does not widen what that credential can reach. See
[Manage buyer agents](https://docs.apostra.com/v2/setup/buyer-agent-credentials.md) for the credentials a
buyer agent can use and how to grant access.

A buyer agent can act only on advertisers owned by the account it is registered
in. A grant on an advertiser in another account of your organization does not
let it work there today. This is another reason to hold clients in one account
when one agent serves them all.

An advertiser grant between organizations is not the way to do this. A grant
gives the grantee's buyer agents nothing. See
[Manage organization advertiser grants](https://docs.apostra.com/v2/buyer/advertisers/tasks/manage-organization-advertiser-grants.md).

## Limit what each client's work can do

**Read or read and write for each advertiser.** An administrator signed in
directly sets a buyer agent's grant on each advertiser. With `READ`, the agent
reads that advertiser's campaigns, creatives, media buys and reporting, and any
write is refused with `agent_read_only`. With `READ_WRITE` it can write too.
The agent cannot change its own grants. Set them in **Settings → API keys →
Manage buyer agents**, or with `save_buyer_agent`. See
[Set advertiser access](https://docs.apostra.com/v2/setup/buyer-agent-credentials.md#set-advertiser-access).

**Launch is a separate confirmation.** A call to `save_campaign` with
`desiredPhase: "active"` previews the launch and changes nothing. A second call
with `confirmLaunch: true` and the `expectedRevision` from the preview launches
it. If the campaign changed in between, the second call is refused. Your
application can hold that second call behind its own approval. A buyer agent
with only a `READ` grant cannot make it. See
[Build an agent](https://docs.apostra.com/v3/build-an-agent.md#add-buying-steps).

**There is no spend cap per advertiser or account.** You cannot set one today.
The control is the campaign budget: `budget.total`, and an optional
`budget.dailyCap`, set with `save_campaign`. Media buy budgets are allocated
from the campaign's total.

## Client funds

Apostra does not hold a separate prepaid balance for each client, and a launch
does not check one. Before it launches, Apostra checks the account's setup: the
account type, a verified organization identity, a plan, accepted Terms, no
unresolved hold, the media-buying entitlement, and, for consolidated billing,
billing details and payment terms. It does not check whether your client has
funds.

Check your client's funds in your own application before your agent confirms a
launch.

## Add your own fee

You can add your own percentage fee to a campaign with `operatorFees`. You
invoice your client and keep the fee. Apostra does not collect it. It is shown
to your organization and hidden from the client unless you choose otherwise.
Operator fees must be switched on for your organization, and a buyer agent
cannot set one. See [Operator fees](https://docs.apostra.com/v3/operator-fees.md).

## Related

* [Account access](https://docs.apostra.com/v3/account-access.md) covers the accounts a call can reach.
* [Name the account on every call](https://docs.apostra.com/v3/name-the-account.md) covers `accountId`.
* [Authentication](https://docs.apostra.com/v3/authentication.md) covers every credential.
* [Plan & Billing](https://docs.apostra.com/v3/plan-and-billing.md) covers what you pay Apostra.


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