Multi-tenant B2B SaaS: isolation you can prove

What we are building

Your fourth customer asks for their own role names. Your ninth wants email sent from their own SendGrid account. Your fortieth is the one who finds the query that forgot its tenant filter. None of that is on your roadmap, and all of it is in your next two quarters.

This guide builds a contract-management SaaS — companies sign up themselves, invite colleagues, work on their own documents, pay monthly — and spends its time on the part that actually kills timelines: a tenancy model that is enforced rather than remembered, a role hierarchy that does not need re-auditing every time a customer invents a job title, subscription lifecycle, credential handling, usage metering, and the one that bites in month six, changing the schema while people are using the product.

Map your product onto the hierarchy — carefully

Supero has a fixed ownership hierarchy. Getting your product onto it correctly is the single most consequential decision in this build; everything downstream either follows naturally or fights you forever.

Domain            ← you, the vendor           (globally unique)
  └─ Project      ← your product / environment  (its own schemas + API surface)
       └─ Tenant  ← one customer company        (the isolation boundary)
            └─ UserAccount / ApiKey  ← their people and machines

Because scope is carried by the credential rather than the request body, isolation is not something your query code has to remember. A caller cannot widen their own scope by editing a payload, because the scope was never in the payload.

Signup, and the request that follows it

A role model that extends without re-auditing

Roles are strictly hierarchical — a lower level number is more privileged — and a caller can only assign a role strictly below their own. That ceiling is enforced on every role-carrying write, not just in the dashboard. Eight are assignable in your app; two more sit above them and are Supero-staff-only.

Custom roles are relabels, and that is a feature

When a customer wants "Counsel" and "Reviewer" instead of "admin" and "user", register custom role names. A custom role adds zero new control-plane privilege — the hierarchy, the admin-surface routing and the permission list all resolve through its base_role. What it can have is its own data access: object-level policy is looked up by the role name you assigned, so pair every custom role with a PolicyDef of the same name. Skip that and it inherits nothing but the base role's defaults.

POST /api/v1/crud/acme-corp/role
{
  "parent_type": "project",
  "parent_uuid": "<project-uuid>",
  "name": "counsel",
  "display_name": "Counsel",
  "description": "Customer-side administrator",
  "base_role": "tenant_admin"
}

• base_role must be tenant_admin, tenant_user or viewer — a hard ceiling. A custom role can never resolve to a project-, domain- or platform-level privilege whatever you call it.
• You cannot shadow a built-in role name, and you cannot create a custom role whose base_role outranks your own.
• At login and on refresh, the custom name resolves to its base role for privilege purposes — so "Counsel" gets tenant_admin's permission list and the admin surface — while per-entity access still comes from the policy written against "counsel".

Subscriptions, and one honest caveat

The recurring_plan service models the plan lifecycle. (It is named recurring_plan because subscription is a reserved schema name.) membership is the separate, related primitive for "is a member of this org/team" — role-bearing membership, not billing.

For the money itself, stripe_checkout handles hosted checkout and payment links, billing covers charges, customers, subscriptions and invoices, and billing_paypal / billing_razorpay / billing_phonepe cover the regional gateways. Mirror the gateway result onto a payment record with authorize_payment → capture_payment so your own system has a first-class record of it.

Per-customer integrations, and the scope you actually get

Sooner or later a customer asks to send email from their own SendGrid account, or post to their own Slack. In a hand-built SaaS this is a schema change, a secrets-management project and a support burden. Supero gives you most of the way there: credentials live in a per-project credential store, encrypted at rest on Supero Cloud and masked on read, so no secret ever enters your codebase. Know the scope, though — service credentials belong to the project, so every tenant in a project shares them. When one customer genuinely needs their own provider account, register their endpoint in the plugin registry rather than splitting them into a project of their own.

• Your application code never holds a secret. It names a service_id and an operation.
• Wire test keys while you build; switch to live keys in the admin panel — no redeploy, no code change.
• API keys carry a domain/project/tenant scope and are revocable at any time.
• For anything not in the catalog, register the customer's own HTTP endpoint in the plugin registry with its own auth, retry and circuit-breaker settings.

Changing the schema while customers are using it

This is the part of B2B SaaS nobody demos. You need to add a field, rename another, and drop one that was a mistake — and there are now forty tenants with live data on the old shape.

Supero classifies a schema change before applying it. An additive change goes through. A change classified as breaking — removing a previously required attribute, for instance — is rejected synchronously with HTTP 422 rather than silently migrating, and destructive regeneration is refused outright against a live-mode project. The failure mode is a refusal you see immediately in your deploy, not a corruption you find in a support ticket. There is a force_breaking override for when you genuinely mean it; the point is that you have to mean it.

How to build it on Supero

POLICIES = [
    PolicyDef(role="tenant_admin", default_access="full", rules=[]),

    PolicyDef(role="tenant_user", default_access="none", rules=[
        PolicyRule(entity="contract",  can_read=True, can_create=True, can_update=True,
                   filter_field="owner_username", filter_match="$user.name"),
        PolicyRule(entity="template",  can_read=True),
        PolicyRule(entity="org_member", can_read=True),
    ]),

    PolicyDef(role="viewer", default_access="none", rules=[
        PolicyRule(entity="contract", can_read=True),
    ]),
]

[{"event": "@signup",
  "workflow_id": "onboard_new_company",
  "input_map": {"email": "user.email", "name": "user.full_name"}}]

What this build does not give you

• No recurring-charge scheduler. The plan state machine ships; the clock does not. The renewal tick — authorize, capture, renew_period — is a scheduled job you write and operate, and renew_period is cumulative so a blind retry advances the period twice.
• Credentials are per project, not per tenant. "Each customer brings their own SendGrid" is a plugin-registry pattern or a separate project, not a config field.
• Custom roles are labels, not privilege levels. A customer who wants a genuinely new tier of access is asking for something the ladder does not have, and the honest answer is no.
• A breaking schema change is refused, not migrated. That is the right default, but it means the data migration is still yours to write when you genuinely need one.
• Metering tells you usage; it does not price it. Plan limits, overage behaviour and the upgrade path are product decisions you build on top.

Time to deliver

The foundation is the part nobody sees and everybody rebuilds

Every B2B SaaS converges on the same substrate: tenancy, roles, policy, subscriptions, credentials, metering, and a safe way to change the schema. Teams spend their first year building it and their second year fixing it.

The argument for putting this in a platform is not that it is hard. It is that it is identical at every company, and every team that rebuilds it re-earns the same bugs in the same order. If you think you already have it, the test is cheap — run the three adversarial checks from step 6 against what you have today, and see whether all three come back refused.