Support/Using Your App/Administer your tenant account
/

Using Your App

Administer your tenant account

Invite hosted users, manage external users, DataRoles, locations, User Type menus, and the synchronized developer-kit account overlay.

Open raw .md
Who
Active account owners
Data scope
One AppAccount only
Account overlay
Generated on request

An active account owner can open Admin from the application top bar. This is the operating console for that tenant account—not the SaaS builder control plane. Every read and write derives the SaaS app, AppAccount, user, DataRoles, and database route from the signed-in server identity. The browser cannot choose another account by supplying an ID.

What an account owner can see

  • Account status, primary contact information, creation date, and current module inventory.
  • Total and active users, each user’s User Type, assigned DataRoles, location scope, status, and most recent successful login.
  • Active and inactive DataRoles, their record capabilities, AI-read/export/trust/billing flags, and named action-permission keys.
  • Locations, codes, addresses, time zones, managers, ordering, and active state.
  • Builder-approved shared User Types, their current menus and pages, and any account-owned menu override.

What an account owner can change

  • Invite a hosted user by email with a selected User Type, DataRoles, and location scope.
  • Add a real external/headless TenantUser, selecting its User Type, DataRoles, and either specific locations or all-location scope.
  • Activate or deactivate non-owner users with optimistic revision protection.
  • Create DataRoles and explicitly select record, AI, export, billing, and named action permissions. Trust-record and disbursement controls are not available as enforced tenant capabilities yet.
  • Create locations and deactivate an unassigned location. An assigned location is refused rather than silently changing a user’s security meaning.
  • Assign only User Types the SaaS builder enabled for tenant assignment, and narrow or reorder a shared menu only when the builder enabled overrides for that User Type.
Important

The account owner cannot deactivate the active owner or a DataRole assigned to an active owner. A concurrent edit returns a conflict and must be reloaded; it is never silently overwritten.

External users versus hosted sign-in

The Add user form creates a passwordless external identity for delegated/headless API use. The owner supplies the stable external user ID used by their own identity provider. BuildWithHQ stores no invented password and does not return a reusable per-user secret. Their backend exchanges or delegates identity through the supported user-token path, and every operation runs through that TenantUser’s real DataRole and location envelope.

The Invite a hosted user form is an explicit, separate choice. BuildWithHQ sends an expiring, single-use link. The recipient establishes their own password, then signs in through the hosted application. The invitation snapshots the selected User Type, DataRoles, and locations, and applies them atomically only after acceptance.

Note

The raw invitation secret is never stored. Email links keep it in the browser URL fragment so it does not enter ordinary HTTP access logs, and resolve/accept send it only in a CSRF-protected POST body. Resend rotates the secret; revoke, expiry, or successful acceptance prevents reuse.

An invitation can link an existing passwordless external user with the same email or create one intended TenantUser. External-only users remain unable to use hosted sign-in unless the owner deliberately invites them.

Synchronize the Developer Kit account overlay

The canonical Developer Kit ZIP is a public website download; downloading it requires no tenant permission or API key. Protected API calls made with the kit require valid credentials and are limited by their scopes and the caller’s server-verified identity and record permissions. To add one organization’s private account overlay, run tools/sync_account_overlay.py with a short-lived tenant session. The server requires owner access or delegated Developer Kit and design capabilities before returning Account Overlay 2.1.0. The original Admin → Developer kit → Download ZIP action provides the same protected, account-specific overlay for offline import; it is not the public kit download. The overlay contains:

  • account.json with this account’s safe SaaS/AppAccount identity and authentication mode, but no credential;
  • capabilities.json with all 23 published platform capabilities;
  • contracts/operations.json with all 242 published tenant-runtime operations and their exact methods and routes;
  • catalog/lego-modules.json with the ID-addressed module schema routes currently supported for declarative composition;
  • the current User Type/menu presentation contract, effective account page JSON, and active binding metadata (never connector secrets);
  • working same-origin account, module, Lego-catalog, and declarative-composite TypeScript clients;
  • copyable React account-administration, live-module and Lego-composite panels, plus Contacts directory and Work Orders board samples that load real catalog IDs rather than fixtures;
  • database schema/release and catalog fingerprints for compatibility checks;
  • pinned package/typecheck configuration, an offline validator, and a SHA-256 manifest covering every generated file.

Built-in capabilities are enabled by default. Pages and menus control where a capability is pinned; they are not feature switches. Separately purchased or installed modules retain their own activation lifecycle. Publication in the ZIP is still not an authorization grant: every request reapplies the current TenantUser, DataRole, location, User Type, record and action-policy checks.

The archive never contains a tenant access token, password, SQL connection, provider credential, raw customer row, placeholder binding, or a way to widen permissions. The included AppAccount ID is configuration—not authorization. A current tenant session is still required on every call, and the browser must never receive a server-side draft, live, CLI, or MCP credential.

Install and verify the overlay

$env:BWHQ_TENANT_ORIGIN = 'https://your-tenant.example.com'
$env:BWHQ_TENANT_ACCESS_TOKEN = '<short-lived tenant session bearer>'
python .\tools\sync_account_overlay.py

The tenant token is used only for the authorized account-overlay download and is never written to disk. Draft and live Developer API keys belong in trusted backend secret storage; they authorize only their permitted API operations and are never substitutes for the tenant session required by account-overlay sync or exposed to browser code.

npm install
npm run check

npm run check type-checks the clients and React starters, verifies every manifest hash, checks the account-scoped catalog shape, and refuses placeholder bindings or credential-shaped content. Choose an operation from contracts/operations.json, pass its route, query, and body values to TenantModuleClient.invoke, and render the authorized JSON directly or through LiveModulePanel.

When to synchronize again

Run the tool with --replace after an installed-module, shared User Type/menu, account menu, page, binding, database upgrade, or tenant API contract change. Compare compatibility.json and the manifest in source control rather than assuming an old overlay still represents the running account.

Support lane manager

The editable organization-owned email/SMS lane manager is included in the current kit. See support lanes, installation and API contracts.

Capability review: 2026-09-14. See current features and setup requirements, the generated API Map and first-class module inventory.