Invite and manage a client's access

save_advertiser_access lets you give a person at a client company access to one advertiser in your Seller Account, and manage that access afterward. Read the advertiser first with get and kind: "advertiser_access" and use only the actions it offers.

Only an organization administrator signed in directly can make these changes. API keys, service tokens, agents acting for someone else, and impersonated or parent-account sessions are refused. Client access must also be turned on for your account.

The same changes are available over REST. They share one set of rules with this tool; see List organization advertisers.

Choose an action

Field	Used by	Meaning
`action`	all	`invite`, `decide`, `change_role`, or `revoke_lifecycle`.
`advertiserId`	every action	The advertiser. For `revoke_lifecycle`, the advertiser that owns the lifecycle.
`email`	`invite`	The one person to invite.
`operatorDomain`	`invite`	The invited person’s company domain, for example `agency.example`.
`role`	`invite`, `change_role`	`advertiser-viewer`, `advertiser-editor`, or `advertiser-admin`.
`eligibilityRevision`	`invite` (optional)	`invite.eligibilityRevision` from the read. Leave it out to use the current one.
`admissionId`	`decide`, `change_role`	The client, from `people`.
`decision`	`decide`	`approve`, `suspend`, `reactivate`, or `revoke`.
`expectedRevision`	`decide`, `change_role`	The client’s `revision` from the read.
`reason`	`decide`, `change_role`, `revoke_lifecycle`	Why, in a sentence. It goes in the audit record.
`lifecycleId`	`revoke_lifecycle`	An older self-serve access record, from `lifecycles` for that advertiser.

A field an action does not use is refused rather than ignored.

Invite a client

{
  "action": "invite",
  "advertiserId": "100",
  "email": "operator@agency.example",
  "operatorDomain": "agency.example",
  "role": "advertiser-viewer"
}

Apostra emails the person a one-time link. They sign in with that exact email address and accept. Accepting does not give them access: you still approve them. The reply tells you whether the email was sent or failed. If it failed, read the advertiser again; invite.available is true while the same invitation can be sent again. Sending the same invitation again does not create a second one.

Approve, suspend, reactivate, or revoke

{
  "action": "decide",
  "advertiserId": "100",
  "admissionId": "9f24ad79-d930-40b0-81a1-7c56be518f51",
  "decision": "approve",
  "expectedRevision": "3",
  "reason": "Confirmed with the client's account lead."
}

Approve works once the person has accepted the invitation. Suspend and revoke take effect immediately. They stop the person’s access without erasing the advertiser’s campaigns or history.

Change a role

{
  "action": "change_role",
  "advertiserId": "100",
  "admissionId": "9f24ad79-d930-40b0-81a1-7c56be518f51",
  "role": "advertiser-editor",
  "expectedRevision": "4",
  "reason": "They now edit campaigns."
}

You can change the role of an approved person who has accepted. The roles are fixed bundles: a viewer reads, an editor reads and writes, and an administrator can also administer the advertiser. None of them includes billing or payment.

End older self-serve access

revoke_lifecycle ends an older self-serve access record. Name the advertiser and take the lifecycleId from that advertiser’s lifecycles on the read, where canRevoke is true:

{
  "action": "revoke_lifecycle",
  "advertiserId": "100",
  "lifecycleId": "55",
  "reason": "No longer a client."
}

A lifecycle that belongs to another advertiser, is already revoked, or is on a System advertiser is refused.

When a call is refused

Refusal	What to do
Not an administrator signed in directly	Ask an organization administrator to make the change.
Client access is not enabled for the account	Contact Apostra.
The action is not offered	Read the advertiser again and use `availableActions`.
The revision is out of date	Someone changed this client since you read it. Read again and retry.
The advertiser is a System advertiser	Apostra operates it. Its access cannot be changed.
The client does not belong to that advertiser	Check `advertiserId` and `admissionId`.

If a reply is lost, read the advertiser again before retrying. A change that already went through never repeats; the retry is refused because the action is no longer offered, and the read shows the result.

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Invite and manage a client's access

Choose an action

Invite a client

Approve, suspend, reactivate, or revoke

Change a role

End older self-serve access

When a call is refused

​Choose an action

​Invite a client

​Approve, suspend, reactivate, or revoke

​Change a role

​End older self-serve access

​When a call is refused

Choose an action

Invite a client

Approve, suspend, reactivate, or revoke

Change a role

End older self-serve access

When a call is refused