> ## 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. # Account > Your current account context, the accounts under your organization, membership access, and notification preferences An **account** is the entity the authenticated user is operating as. Every buyer request runs in the context of one account, identified by a numeric `id` and carrying a `role` (`MEMBER`, `ADMIN`, or `SUPER_ADMIN`) that gates what the caller can do. A user can belong to several accounts; the account API lets you read the current context, list the accounts you can access, and switch your integration between them. ## Account model Full user-context responses returned by account creation and switching separate the product an account uses from its access and approval state: | Field | Meaning | | - | - | | `nodeKind` | `ACCOUNT` for a product workspace or `CONTAINER` for an organization that governs accounts. | | `accountType` | `BUYER` or `SELLER` for accounts, or `DEVELOPER` for a Developer account, which owns agents and has no Buyer or Seller tools (Developer accounts are in a closed preview). Some compatibility responses use `PARTNER` to project the organization's sales-agent offering; it is not a separate account. An organization container has no core account type. | | `customerRole` | Compatibility field for Buyer and Seller integrations. Use `accountType` for new Buyer and Seller reads. The sales-agent offering has no `customerRole` equivalent, and a Developer account's `customerRole` is a placeholder: read `accountType` to tell it apart from a Buyer account. | | `enabled` | Whether people and API clients can enter the account. It does not grant Buyer live-spend eligibility or Partner registration, certification, or commercial approval. | | `buyerAccessPosture` | Deprecated compatibility projection. It is not operation authority; use Buyer Setup capability verdicts. | | `registrationStatus` / `commercialStatus` | Independent states on an organization's sales-agent offering. Registration is `AVAILABLE` or `REGISTERED`; commercial status is `INACTIVE`, `ACTIVE`, `SUSPENDED`, or `EXITED`. A newly enabled offering starts `AVAILABLE` / `INACTIVE`, and registration or certification does not grant commercial approval. | Each account has its own registered `customerDomain` and membership settings. When an enterprise organization manages more than one account, organization membership grants management access through that hierarchy but does not create direct account membership. Separately, each user manages their own **notification preferences** — the set of event types and channels (`email`, `in_app`) they opt into. ## Key concepts | Concept | Description | | - | - | | Current account | The account context the request authenticates as — `id`, `company`, `name`, `role`, `customerDomain` | | Organization | The top-level entity in the hierarchy; only accounts created under an organization can be deleted | | `customerDomain` | The account's registered domain; required before domain auto-join can be enabled | | Operator identity | The seller-facing AdCP key for this buyer account: its operator domain and, only for a specific operating unit, a stable `operator_unit.id` | | Membership | Per-account access settings, notably `allowDomainAutoJoin`; defaults on for top-level organizations and off for child accounts | | Notification preferences | Per-user opt-ins of `notificationType` × `channel` | | Role | `MEMBER`, `ADMIN`, or `SUPER_ADMIN`; admin-only operations require `ADMIN` on the target account | ## Manage child accounts in the app Organization administrators can open **Account settings → Organization → Accounts** from the organization or one of its child accounts. The list shows active accounts first; use the status filter to view archived accounts. The pane links to each active account's members and provides **Add account**, **Archive**, and **Restore**. Administrators can see **Add account** even when creation is unavailable; the pane explains why it is disabled. Creation follows the organization's account-capacity rules. Archive shows any campaign or media-buy blockers before you confirm; archived accounts retain their history and still count toward capacity. To archive the buyer account you are working in, open **Account settings → Danger zone**. Organization administrators get **Open organization accounts**, which switches to the organization and opens its account list, because an account cannot be archived while you are using it. Other members are asked to contact an organization administrator. Standalone buyer accounts and buyer organizations have no Danger zone: only an organization's child accounts can be archived. Organizations with no separate Organization group, such as standalone accounts, continue to use **Plan & Billing** for account usage, fees when available, and agreement history. ## Manage accounts with a V3 agent From an organization in the V3 MCP preview, use `search({kind: "account"})` to list its active and archived child accounts. Use `get({kind: "account", id: ""})` for one account. The detail includes its `ACTIVE` or `ARCHIVED` lifecycle status and the organization's commercial terms that the account inherits: the current Terms of Service URL, required and accepted versions, acceptance details, current contract posture, and up to 25 agreement-history entries. These terms belong to the organization; they are not separate child-account terms. Use `search({kind: "member", filter: {accountId: }})` to read an account roster, then `get({kind: "member", id: "", accountId: })` for one membership and role. Member reads do not grant or change access. An organization administrator can call `save_account` for an existing direct child. It accepts only `name` and `settings.company`. The V3 agent surface does not choose the first owner, change members or roles, or archive and restore accounts. Use the Organization Task below for a reviewed lifecycle request. Member access stays in **Organization → Members**. To inspect one managed child from a Buyer or Seller home account, a direct organization administrator or direct Scope3 platform administrator can call `manage_organization` with `action: "inspect_account"`, the exact `parentCustomerId` and `customerId`. The read checks authority on that parent, confirms the child's organization identity, and returns its lifecycle status, archive blockers and parent workspace capacity. It does not switch accounts or change anything. A capped organization list cannot prove that a child is absent. To see the organization itself, use `action: "inspect_organization"` with the exact `parentId`. It returns the organization's total, active and inactive child account counts and its workspace capacity. To request a standard child from the same home account, first call `manage_organization` with `action: "review_create_account"` and the proposed fields. The review says which capacity the account would use and whether it can be requested, and changes nothing. Then call it with `action: "request_create_account"`, the confirmed `orgRef`, exact parent ID, proposed name, Buyer or Seller role, a reason and a stable UUID. A direct organization administrator may request a standard Account under their own organization. A direct Scope3 platform administrator may request one under any exact organization. That administrator can use the separate `review_demo_storefront` and `request_demo_storefront` actions for a Demo Storefront. Standard Accounts need contracted workspace capacity and plan coverage. Demo Storefronts are exempt from contracted capacity. The tool returns a link. Nothing is created until a person with the required role approves the exact request on the website. Repeat the same call and UUID to check the outcome. No customer switch is needed. To archive or restore one child, first call `manage_organization` with `action: "review_account_lifecycle"`, the exact parent and child IDs, confirmed `orgRef`, current child name, action and reason. Review the returned blockers. Then call `manage_organization` again with `action: "request_account_lifecycle"`, the same fields and a stable UUID. It returns a website approval link; no lifecycle change occurs until an eligible administrator approves it. Archive refuses active work, and restore requires a lifecycle-archived child and a plan that still covers it. Repeat the request with the same UUID to check its recorded outcome. To rename one child, call `manage_organization` with `action: "review_rename_account"`, the exact parent and child IDs, confirmed `orgRef`, the current name from inspection, the new name and a reason. Then call it with `action: "request_rename_account"`, the same fields and a stable UUID. The rename waits for website approval, and it is refused if the current name changed after the request. To check a request later without resending it, call `manage_organization` with `action: "check_request_outcome"`, the exact `parentId`, confirmed `orgRef`, the kind of request (`create_account`, `demo_storefront`, `account_lifecycle` or `rename_account`) and its original UUID. It returns the recorded state and, once the change ran, its result. ## Create a Buyer child through MCP From an organization in the V3 MCP preview, an agent can create a Buyer child account under that exact organization. Nothing is created until an organization administrator approves it on the Apostra site: If the agent starts in a Buyer Account, call `get_status` to find the Organization account ID, then call `switch_account` with that ID. The agent can call `get_status` again in the Organization to see its child accounts and can switch back to a Buyer Account afterward. An MCP host that keeps its initial tool list also lists the Organization tools when the signed-in user can reach the Organization. Each tool still checks the selected account and the caller's permissions when it runs. 1. `review_buyer_child_account` with the organization's ID and the proposed name shows the contracted account capacity, who is asking, and what will change. It is read-only. 2. `request_buyer_child_account` with the same organization ID, the name and an `idempotencyKey` records the request and returns `approval_required` with a link to the approval page. Show the person the link. If the organization has no account capacity left, the request is refused and nothing is recorded. 3. An organization administrator opens the link, signed in in their own browser, and approves or rejects the request. It can be a different administrator from the one who asked. An unanswered request expires after 24 hours. See [Approving agent requests](/v2/concepts/web-approvals). 4. Call `request_buyer_child_account` again with the same key and name to get the outcome: the new account's ID once it is created, or the reason it could not be created (for example, no account capacity left). Creating the account sends no invitation, changes no feature flag and creates no media buy. Organization administrators inherit access to the new account. It does not make the account ready to buy: complete Buyer Setup, and any required terms, plan and payment steps, separately. This works in text-only MCP hosts. ## Task reference Confirm whole-operator or specific-unit scope before new AdCP 3.2 provisioning `GET /accounts/current` — your current context `GET /accounts` — accounts you can access `PATCH /accounts/:customerId/domain` — set the registered domain `GET /accounts/:customerId/membership` — read access settings `PATCH /accounts/:customerId/membership` — toggle domain auto-join `GET /notification-preferences` — your opt-ins `PUT /notification-preferences` — replace your opt-ins This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.