Tenants

Types: your word for a tenant

A tenant type is the word you name a kind of tenant by: Company, Shop, Class. Your pages will be able to show it once they can read tenants. You make the list; every tenant is of one of your types. A type also says what a new tenant of it starts as (its start status): active unless you pick another, for example pending for shops you approve first. A site has one type of each name: adding a name it already has is refused, so set the rules on the type you have.

Status

A tenant is always one of four: pending, active, suspended or closed. You can change it at any time. Nothing is ever deleted, whatever the status. A closed tenant keeps its members; you cannot add a member to it or change a member’s role until you set it to another status (“This tenant is closed: reopen it first to change its members.”). Taking a member out of a closed tenant still works.

Closing a tenant also stops its billing: a card subscription paid for the tenant is cancelled at Stripe at once, and every billing account it holds stops (an unpaid invoice is cancelled; paid invoices and payments stay in your history). Suspending a tenant does not stop its billing, and reopening a closed one does not start it again. If Stripe can’t cancel the subscription right now, or the site’s Stripe is not connected, the tenant is not closed and you’re told what to do. Because it stops billing, only someone who may change your site’s billing can close a tenant that pays. A payment that arrives after the close gives nothing: it shows in your payment history with the reason, so you can refund it.

Members and tenant roles

Any member of the site can be added to a tenant, and one member can be in several tenants. Every site has two built-in tenant roles, Admin and Member (a new member gets Member unless you pick another), and you can add roles of your own, like Teacher or Billing. A tenant role is a name in that tenant; it gives no powers of its own. Tenant roles are separate from the site’s roles.

How you manage tenants

Ask the AI chat, or your own AI client connected over MCP: “Add a tenant type Company”, “Make a company called Acme and add Sara as its Admin”. The AI picks types, tenants, roles and members from your site’s lists by name; you never type an id. The tools are site_listTenantTypes, site_listTenantRoles, site_listTenants, site_getTenant, site_listTenantMembers, site_createTenantType, site_updateTenantType, site_createTenantRole, site_createTenant, site_renameTenant, site_setTenantStatus, site_closeTenant, site_addTenantMember, site_removeTenantMember and site_setTenantMemberRole. Lists of tenants and of a tenant’s members come a page at a time, at most 100 per page.

In a workspace with members, anyone who can see the site can read its tenants; changing them needs the “Edit and publish sites” permission, the same as changing the site’s members.

Records that belong to a tenant

Two building blocks let each tenant see only its own records: a table setting and a rule. Combine them with any other rule; nothing about them is tied to one kind of site.

1. Records belong to a tenant, a setting per table (off by default): ask the AI “Records in Leads belong to a tenant” (site_setTableRowsBelongToTenant). From then on every record a member adds through your site carries their tenant, set by Serenities, never typed. A member in several tenants says which of their tenants a record is for; a tenant that is not theirs is refused. A member can never move a record to another tenant. Records you add yourself have no tenant unless you name one, and a record with no tenant is yours only.
2. Same tenant, a rule on the table’s access rules: “the record belongs to one of the member’s tenants” (closed tenants do not count). It works on reading, adding, changing and deleting, alone or with any other rule. “Not same tenant” works on one record at a time; on a whole list it shows the member nothing, like “not the creator”.

Use tenants from your pages

Your pages use tenants through the site’s SDK, as the signed-in member. Each type has two rules you set (ask the AI, or site_updateTenantType): who may create a tenant of this type and who may join one by a link. They are ordinary access rules: signed in, a role, a plan, a profile value, or a mix. With no rule, only you make tenants of the type.

• tenants.mine(): the member’s own tenants, with their role in each.
• tenants.create({ typeId, name }): makes a tenant when the type’s create rule lets them; they become its tenant admin.
• tenants.roles(): the tenant roles, so a page picks one by name.
• For a tenant’s own admin (its tenant admin): tenants.members(tenantId) (a page at a time), tenants.invite(tenantId, email, roleId), tenants.setRole(tenantId, memberId, roleId) and tenants.removeMember(tenantId, memberId).
• Colleagues join only by an invite they accept. A tenant admin invites by email; the person gets one email, sent from your site’s own sending account (connect one in Settings → Email first: without it invites are refused), whose link opens your site with #invite=… at the end. Your page reads it and, when they are signed in, calls tenants.acceptInvite(token) (or tenants.declineInvite(token)); someone new signs up with it, user.signup(email, password, { invite: token }), and joins the tenant in the same step. The signed-in or sign-up email must be the one invited. An invite works once, for 7 days; a tenant has at most 50 invites waiting (see the limits below). A tenant admin cannot add someone directly; you still can, from the dashboard or the AI.
• Waiting invites. Any admin of the tenant sees the invites still waiting with tenants.invites(tenantId) (the address, the role, when it was sent and when it runs out; never the link) and takes one back with tenants.revokeInvite(tenantId, inviteId): its link stops working and its place under the limit is free. An admin who is removed, leaves or is given another role takes the invites they sent in that tenant with them. You can do the same from the AI or MCP (site_listTenantInvites, site_revokeTenantInvite).
• tenants.leave(tenantId): any member leaves, the last one too; the only Admin hands the role on first while others remain.

A tenant the member is not in looks the same as one that does not exist, and a tenant admin manages only their own tenant. A member in several tenants names one of theirs when they add a record: entities.Leads.create(data, { tenantId }). A function that lives in the site adds records the same way, ctx.tables.createRow('Leads', data, { tenantId }): run for a member it records the member's own tenant; run on a schedule or an event it may name any tenant of the site.

Build a multi-tenant SaaS

Use tenants when several people per customer share records: a company and its staff, a shop and its staff, a class and its students. When each customer is one person with their own records, you are building a normal SaaS: plans and the “Creator” rule are enough, no tenants needed.

1. Turn on sign-in for the site. A setting to choose “individuals or multi-tenant” in the sign-in settings is coming next; until then your page creates the tenant (step 5).
2. Add a tenant type, your word for a customer (Company), or use the one the site already has, and give it the create rule “Signed in” so new customers can start their own (site_createTenantType, site_updateTenantType).
3. Turn on “Records belong to a tenant” for every table that holds a customer’s own data (site_setTableRowsBelongToTenant). Never add a “company” column by hand.
4. Give those tables the rule “Same tenant” (same_tenant) for reading, adding, changing and deleting, alone or with a plan: “Same tenant and has paid for Pro”.
5. Sign-up page: after signing up, the customer names their company (tenants.create) and becomes its tenant admin.
6. Colleagues: the tenant admin manages the tenant’s people from a People page (tenants.members, tenants.invite, tenants.invites, tenants.revokeInvite, tenants.setRole, tenants.removeMember), and an invite page accepts the emailed link (tenants.acceptInvite, or sign-up with the invite). You (or the AI) can also add someone directly (site_addTenantMember).
7. Buyers with no tenant (a seller’s own customers): they sign up as plain members and belong to no tenant; give the tables they use their own rules, such as products anyone can read and orders only their creator sees.
8. A company pays once; its people get access: sell a plan (a product that gives an access, like pro) and use it in the tables’ rules. The tenant admin pays for the whole tenant on your pricing page (payments.checkout('pro', { forTenant }), by card, another payment provider or a bank transfer you approve); only an admin of that tenant can. Every member of the tenant then has pro while the tenant is open; someone who leaves loses it right away, and a person in two tenants gets both. A monthly plan bills the tenant, and its admin pays the tenant’s invoices. You can also give, pause or remove an access for a whole tenant on Payments → Members & access, or ask the AI. A person can still buy a plan just for themselves.

Limits

The same on every plan. Names (of tenants, types and roles) are 1 to 200 characters. At a limit, the change is refused with the words below and nothing is saved.