Org management

The Org Management module is the platform's tenant-administration surface. It covers organisation profile, billing and credit purchases, subscription plans, account lifecycle (cancel/reactivate), pre-approved signups, ownership transfers, asset transfers between orgs, and service agreements. Most endpoints require ConfigAdmin or higher; some are gated to RootAdmin for platform-operator-only actions.

Profile management

profile returns the company record, customer record (the org owner), and address. profile/update accepts modifiable company fields (display name, interests). profile/customer updates the owner's personal profile. The :orgId? form on profile allows root-org admins to inspect any org; non-root callers see only their own.

Addresses

Per-user address book — billing, shipping, mailing addresses tied to the owner. Used for invoicing and tax compliance.

Billing and credits

balance returns the org's current credit balance. buy-credits takes a payment-method ID and amount, creates a Stripe payment intent, and returns the secret for client-side confirmation. complete-payment finalises after the client confirms with Stripe.

// 1. Initiate
const { paymentIntentClientSecret, transactionId } = await fetch(
  '/api/org-management/billing/buy-credits',
  {
    method: 'POST',
    headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
    body: JSON.stringify({
      amount: 100,
      currency: 'USD',
      gateway: 'stripe',
      paymentMethodId: 'pm_abc',
    }),
  },
).then(r => r.json());

// 2. Confirm with Stripe Elements

// 3. Finalise
await fetch('/api/org-management/billing/complete-payment', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({
    paymentIntentId: 'pi_abc',
    transactionId,
    gateway: 'stripe',
  }),
});

gift-credits and add-credit are platform-operator endpoints (root-admin only) for promotional grants and refunds.

Subscription management

plans returns the catalogue (free, basic, pro, team, enterprise — see Usage and pricing for details). current returns the org's active subscription. create, upgrade, downgrade, cancel are the customer-facing lifecycle. admin/update is the operator-only override (root admin) for plan corrections.

Effective dates: upgrades are immediate (prorated), downgrades and cancellations default to end-of-period.

Account lifecycle

cancel ends the org's account — cancels the subscription, optionally deletes data, suspends API access. reactivate reverses a cancelled state (admin only).

Pre-approved signups

For closed-beta or invitation-only platforms. Add an email or signup code to the allowlist. The signup flow checks validate before creating the new org. Codes can be single-use or multi-use with an expiry.

Organisation registration

Operator endpoints (root-admin only) to create and delete organisations. The delete endpoint optionally tears down sites, dev environments, and K8s resources.

Additional services

Add-on services like priority support, dedicated success manager, increased storage, premium domain registration. available returns the catalogue (filterable by category). purchase initiates payment; complete-payment finalises after the gateway confirms.

Transfers

Operator endpoints for org-level changes:

• ownership — transfer the org to a new owner email (creates the new owner with admin role).
• change-email — update the org's primary email without a full ownership transfer.
• assets — move records of one datatype between orgs (copy or move mode).
• assets-bulk — move multiple datatypes in one operation.

These are typically used for partial deprecation, customer mergers, white-label hand-offs, and fixing accidentally-created orgs.

Service agreements

For services with their own terms (premium AI models with separate licensing, third-party integrations with usage agreements), the org explicitly accepts the terms before the service is available. The pricing endpoint returns current rates and terms; accept records the acceptance with metadata; revoke cancels.

Feature flags

Feature flags are stored on the org record and read by the application code on every request. They're not exposed as standalone endpoints — they're a field on the org's features array updated via profile/update or subscription/admin/update. Plan tiers grant default flags (e.g. pro plans get automation, multi-site); custom flags layer on top for per-org overrides.

Permissions

Action	Required role
Read own profile	Any authenticated user
Update own profile	ConfigAdmin
View other org's profile	RootAdmin (root org only)
Buy credits	ConfigAdmin
Gift credits	RootAdmin
Cancel subscription	ConfigAdmin
Admin update subscription	RootAdmin, RootPowerUser
Transfer ownership	RootAdmin, RootPowerUser, ConfigAdmin
Pre-approved signups	RootAdmin, ConfigAdmin
Org registration / deletion	System, RootAdmin, RootPowerUser

The full permission matrix is in src/users/decorators/permission.decorator.ts.