> ## 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 > Read your current storefront account, manage membership, and set notification preferences The **account** endpoints expose your current storefront account. Use them to read its context, list accounts you can switch into, set the registered company domain, control domain auto-join, and manage notification opt-ins. ## Account model Full user-context responses returned by account creation and switching use `nodeKind` to distinguish a Buyer or Seller account from an organization container. `accountType` is the canonical product field for those accounts; `customerRole` remains as a compatibility field for Buyer and Seller integrations. Some compatibility responses use `accountType: PARTNER` to project the organization's sales-agent offering. That projection is not a separate account and has no legacy `customerRole` equivalent. `enabled` only controls whether people and API clients can enter the account. It does not make a Buyer live-eligible or grant Commercial Partner approval. Some compatibility responses still expose `buyerAccessPosture`; it is deprecated and is never operation authority. Buyer Setup derives the applicable Buyer capabilities instead. Sales-agent offering projections expose registration as `AVAILABLE` or `REGISTERED` and commercial status as `INACTIVE`, `ACTIVE`, `SUSPENDED`, or `EXITED`. A newly enabled offering starts `AVAILABLE` / `INACTIVE`, so enabling, registration, or certification never implies commercial access. All examples use the storefront base URL: ``` https://api.apostra.com/api/v2/storefront ``` Authenticate every request with `Authorization: Bearer $SCOPE3_API_KEY`. Your account context is resolved from the API key. Domain and membership operations require the `ADMIN` role on the target account. ## Key concepts * **Registered domain.** An account can carry one `customerDomain`. It gates domain auto-join and, for `SELLER` accounts, identifies the company operating the storefront. It initially seeds the storefront's operator domain and remains separate from its public listing domain. * **Storefront operator domain.** A storefront has its own `operatorDomain`, which is the canonical domain the storefront operates as for AAO and buyer-facing identity. It may differ from the account's `customerDomain`. Updating `customerDomain` syncs the storefront only while the storefront operator domain is missing or still mirrors the account's previous registered domain. * **Domain auto-join.** Users with a verified matching-domain email join as members without admin approval when `allowDomainAutoJoin` is true. It defaults on for top-level organizations and off for child accounts, and requires a `customerDomain` to be set. Admins can explicitly override the default. * **Notification opt-ins.** Preferences are a full set of `{ notificationType, channel }` pairs. The update call replaces all existing opt-ins. ## Manage child accounts in the app Organization administrators can open **Account settings → Organization → Accounts** from the organization or one of its child accounts. This pane lists the organization's child accounts, links to each active account's members, and provides **Add account**, **Archive**, and **Restore**. 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. A user with billing access who does not get the Organization section, such as an Apostra platform administrator who is not a member of the organization, manages child accounts in **Plan & Billing → Accounts**. That tab also shows 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. ## Task reference Authenticated account context Accounts you can switch into Set the account's registered domain Read domain auto-join setting Toggle domain auto-join Read your opt-ins Replace your opt-ins ## Related Every operation in one place Audit feed and reporting metrics Shared error contract This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.