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

# Invite and manage a client's access

> Invite a client to one of your advertisers, approve or suspend them, and change their role

`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"`](/v2/buyer/advertisers/tasks/read-advertiser-client-access)
and use only the actions it offers.

<Note>
  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.
</Note>

The same changes are available over REST. They share one set of rules with this
tool; see [List organization advertisers](/v2/buyer/advertisers/tasks/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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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.


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