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

​

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: "<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>", accountId: <account-id>}) 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.
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