Account

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: Each account has its own registered customerDomain and membership settings. The MCP customer_list response also includes accountType. Developer accounts report DEVELOPER even when the legacy customerRole is BUYER; organization containers report a null account type. This classification comes from the registered account type, not the account’s name. If the type cannot be verified, the list returns an unavailable error instead of reporting a guessed type. 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

​

Sessions

Sessions will show the exchanges that an approved seller source has retained for your buyer account. This is being enabled in stages. Until it is enabled for your account and at least one source, Sessions does not appear in the buyer rail. When available, you can read only your own buyer-visible requests and answers. You cannot see a seller’s private notes, coaching, lessons, internal reasoning, or records from another buyer. Sessions is read-only for buyers: you cannot add notes, edit a proposal, send a message, or manage lessons there.

​

Manage child accounts in the app

Organization administrators can open 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 plan coverage and the limit of 25 accounts created per organization in 24 hours (see Accounts in an organization). Archive shows any campaign or media-buy blockers before you confirm; archived accounts retain their history. To archive the buyer account you are working in, open 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: "<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: <account-id>}}) to read an account roster, then get({kind: "member", id: "<member-id>", memberAccountId: <account-id>}) for one membership and role. Member reads do not grant or change access. The organization administrator changes child accounts with save_account, working in the organization account. A call with no id creates a child. A call with id and name renames one, and isArchived archives (true) or restores (false) it. Each of those writes is recorded for website approval: the tool returns an approval_required result with a link, nothing changes until an administrator of that organization approves the exact request on the website, and the agent never approves anything itself. Repeat the same call with the same idempotencyKey to see the recorded state, and once it ran, its result. A rename, archive or restore also needs a reason of 10 to 300 characters, which the approver sees. A rename sent without a reason and an idempotencyKey is refused with a validation error that names them; it does not save at once. get and save_account still accept the earlier accountId in place of memberAccountId and id while connected tool lists refresh. To create a child, send accountType (buyer, seller or developer), a name, a reason and an idempotencyKey. A seller also needs operatingMode, the Seller product, and any child may carry a customerDomain. A platform operator can instead send accountType: "seller" and demoStorefront: true (no operatingMode) to create a Demo Storefront. A Buyer or Seller Account needs plan coverage and counts toward the 25 accounts an organization can create in 24 hours. An organization holds one Developer account, which holds any number of agents; a second is refused. Setting dryRun: true runs every check the real request runs and records nothing, so the preview cannot differ from the request that follows. Send no idempotencyKey with a dryRun. A preview of an archive lists the campaigns and media buys that block it, and restore needs a child that was archived and a plan that still covers it. The organization account’s get_status reports its total, active and inactive child account counts, the accounts it uses, and whether its Developer account exists. If it does not, get_status offers the save_account call that creates it. For one child, get({kind: "account", id, include: ["lifecycle", "capacity"]}) adds the archive state, whether the child can be archived and the counts of campaigns and media buys that block it, and the accounts the organization uses. The reads and every write check that you are an administrator of that exact organization. Send organizationId to act in an organization you are not connected to, for example from a child account you administer through its parent. The server checks that you directly administer that organization (or are a Scope3 platform operator) before it reads anything else. Without it, the call acts in the organization account you are connected to. The V3 agent surface does not choose the first owner or change members or roles. Member access stays in Organization → Members. A settings.company change is a display label, so it is saved at once and needs no approval. Delegated, machine, impersonated and switched-in sessions are refused, because the administrator check needs a direct session. Only a direct Scope3 platform operator can create a Demo Storefront, and the operator must name the customer’s organization with organizationId.

​

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 name it with accountId on each call. The agent can call get_status with that accountId to see the Organization’s child accounts, and name a Buyer Account again on its next call; nothing is switched. 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 account the call names and the caller’s permissions when it runs. See Name the account on every call.

1. review_buyer_child_account with the organization’s ID and the proposed name shows 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’s plan does not cover a Buyer Account, 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.
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, the plan no longer covers a Buyer Account).

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