Articles/App Development

▣ App Development/2026-04-06Advanced

Antigravity × Multi-Tenant SaaS in Production: Supabase RLS × Stripe Metered Billing × RBAC

A production-grade guide to building multi-tenant SaaS with Antigravity IDE. Learn tenant isolation with Supabase Row Level Security, usage-based billing with Stripe Metered Billing, and fine-grained access control with RBAC — with full implementation code.

antigravity⁴⁶⁴ saas¹⁰ supabase⁷ stripe⁹rbacmulti-tenantapp-dev⁵⁴

✦ Premium Article

Setup and context: Why Multi-Tenant Architecture Is Hard to Get Right

When launching a SaaS product as an indie developer, multi-tenant architecture is often the first real technical wall you hit. A "tenant" is the unit of organization or company that uses your SaaS — each tenant needs an isolated data space while sharing the same underlying infrastructure.

Get tenant isolation wrong and you risk serious security incidents: data from one tenant leaking into another. Build fully isolated infrastructure per tenant and costs balloon out of control.

This guide covers how to build production-grade multi-tenant SaaS using Antigravity IDE, built on three pillars:

Supabase RLS — tenant isolation at the database layer
Stripe Metered Billing — usage-based pricing tied to API consumption
RBAC — role-based access control within organizations

This article targets developers who already understand Next.js and Supabase fundamentals and are ready to ship a real SaaS product.

Three Patterns for Multi-Tenant Architecture

Before writing a single line of code, it's worth understanding the three main patterns for multi-tenancy.

Pattern 1: Shared Database, Shared Schema (used in this guide)

All tenants share the same tables, differentiated by a tenant_id column. This is the most cost-effective approach and works beautifully with Supabase's Row Level Security. The vast majority of SaaS products don't need anything more than this.

Pattern 2: Shared Database, Separate Schemas

Each tenant gets its own PostgreSQL schema. Provides stronger data isolation but makes migrations significantly more complex.

Pattern 3: Separate Databases

Each tenant has a fully independent database. Offers the highest security guarantees but comes with substantial cost and operational overhead.

In this guide, we use Pattern 1 and achieve complete tenant isolation through RLS policies.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦A production-ready design pattern that unifies tenant isolation, usage-based billing, and RBAC in a single schema

✦The RLS `auth.uid()` re-evaluation trap, and how wrapping it in a subquery cut a query from 470ms to 8ms

✦An idempotency-key design that stops Stripe metered double-counting, and why monthly resets should key off the billing period, not the invoice

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Step 1: Database Schema Design

Open a new project in Antigravity and start with schema design. Hand the agent this prompt:

Design a database schema for a multi-tenant SaaS application.
Requirements:
- organizations table (the tenant entity)
- Many-to-many between users and organizations (membership)
- Roles: owner / admin / member
- All resources (projects, etc.) are linked via organization_id
- Optimized for Supabase RLS

The agent will generate a base schema like this:

-- organizations table (the tenant)
CREATE TABLE organizations (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name        TEXT NOT NULL,
  slug        TEXT NOT NULL UNIQUE,        -- URL-friendly slug (e.g. "acme-corp")
  plan        TEXT NOT NULL DEFAULT 'free', -- free / starter / pro / enterprise
  stripe_customer_id TEXT UNIQUE,
  stripe_subscription_id TEXT,
  api_usage_this_month INTEGER DEFAULT 0,  -- monthly API call counter
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  updated_at  TIMESTAMPTZ DEFAULT NOW()
);
 
-- organization_members (links users to tenants)
CREATE TABLE organization_members (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
  user_id         UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  role            TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'member')),
  invited_by      UUID REFERENCES auth.users(id),
  accepted_at     TIMESTAMPTZ,
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(organization_id, user_id)
);
 
-- projects table (example tenant-scoped resource)
CREATE TABLE projects (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
  name            TEXT NOT NULL,
  description     TEXT,
  created_by      UUID NOT NULL REFERENCES auth.users(id),
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW()
);
 
-- api_usage_logs (for Stripe metered billing)
CREATE TABLE api_usage_logs (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
  user_id         UUID NOT NULL REFERENCES auth.users(id),
  endpoint        TEXT NOT NULL,
  tokens_used     INTEGER NOT NULL DEFAULT 0,
  created_at      TIMESTAMPTZ DEFAULT NOW()
);

Index Design

Don't skip indexing — these are essential for RLS performance:

-- Index every column used as an RLS filter
CREATE INDEX idx_projects_org_id ON projects(organization_id);
CREATE INDEX idx_api_usage_logs_org_id ON api_usage_logs(organization_id);
CREATE INDEX idx_organization_members_user_id ON organization_members(user_id);
CREATE INDEX idx_organization_members_org_id ON organization_members(organization_id);

Step 2: Tenant Isolation with Supabase RLS

Row Level Security is the backbone of tenant isolation. PostgreSQL's RLS automatically appends WHERE clauses to queries — meaning even if your application code has a bug, data cannot leak across tenants.

Prompt for Antigravity's agent to configure RLS:

Set up Supabase RLS policies for the following tables:
- organizations: visible only to members
- projects: full CRUD only for members of the owning tenant
- api_usage_logs: readable by tenant members, INSERT by any authenticated user (own records only)
- Tenant membership is determined via the organization_members table

Define Helper Functions First

Write DRY RLS policies by defining helper functions upfront:

-- Returns true if the current user is a member of the given org
CREATE OR REPLACE FUNCTION auth.is_org_member(org_id UUID)
RETURNS BOOLEAN
LANGUAGE plpgsql SECURITY DEFINER
AS $$
BEGIN
  RETURN EXISTS (
    SELECT 1 FROM organization_members
    WHERE organization_id = org_id
      AND user_id = auth.uid()
      AND accepted_at IS NOT NULL
  );
END;
$$;
 
-- Returns the current user's role within a given org
CREATE OR REPLACE FUNCTION auth.get_org_role(org_id UUID)
RETURNS TEXT
LANGUAGE plpgsql SECURITY DEFINER
AS $$
DECLARE
  member_role TEXT;
BEGIN
  SELECT role INTO member_role
  FROM organization_members
  WHERE organization_id = org_id
    AND user_id = auth.uid()
    AND accepted_at IS NOT NULL;
  RETURN member_role;
END;
$$;

RLS Policies for the projects Table

-- Enable RLS
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
 
-- SELECT: tenant members only
CREATE POLICY "projects_select_policy" ON projects
  FOR SELECT
  USING (auth.is_org_member(organization_id));
 
-- INSERT: any tenant member (must set created_by to own UID)
CREATE POLICY "projects_insert_policy" ON projects
  FOR INSERT
  WITH CHECK (
    auth.is_org_member(organization_id)
    AND created_by = auth.uid()
  );
 
-- UPDATE: admins and above only
CREATE POLICY "projects_update_policy" ON projects
  FOR UPDATE
  USING (
    auth.get_org_role(organization_id) IN ('owner', 'admin')
  );
 
-- DELETE: owners only
CREATE POLICY "projects_delete_policy" ON projects
  FOR DELETE
  USING (
    auth.get_org_role(organization_id) = 'owner'
  );

Optimizing RLS Performance

Subqueries inside RLS policies run on every query, which can degrade performance under load. Use SECURITY DEFINER STABLE functions to benefit from PostgreSQL's intra-query caching:

-- Returns all org IDs the current user belongs to (cached within query)
CREATE OR REPLACE FUNCTION auth.get_user_orgs()
RETURNS UUID[]
LANGUAGE plpgsql SECURITY DEFINER STABLE
AS $$
BEGIN
  RETURN ARRAY(
    SELECT organization_id FROM organization_members
    WHERE user_id = auth.uid()
      AND accepted_at IS NOT NULL
  );
END;
$$;

Step 3: Type-Safe RBAC Implementation

At the Next.js application layer, implement RBAC with full TypeScript type safety. Have Antigravity's agent generate this type definition file:

// src/types/rbac.ts
 
export type OrgRole = 'owner' | 'admin' | 'member';
 
// Resource types
export type Resource =
  | 'project'
  | 'member'
  | 'billing'
  | 'api_key'
  | 'settings';
 
// Action types
export type Action =
  | 'create'
  | 'read'
  | 'update'
  | 'delete'
  | 'invite'
  | 'manage';
 
// Permission matrix
const PERMISSIONS: Record<OrgRole, Record<Resource, Action[]>> = {
  owner: {
    project:  ['create', 'read', 'update', 'delete'],
    member:   ['create', 'read', 'update', 'delete', 'invite'],
    billing:  ['create', 'read', 'update', 'delete', 'manage'],
    api_key:  ['create', 'read', 'update', 'delete'],
    settings: ['create', 'read', 'update', 'delete', 'manage'],
  },
  admin: {
    project:  ['create', 'read', 'update', 'delete'],
    member:   ['read', 'invite'],
    billing:  ['read'],
    api_key:  ['create', 'read', 'update', 'delete'],
    settings: ['read', 'update'],
  },
  member: {
    project:  ['create', 'read', 'update'],  // no delete
    member:   ['read'],
    billing:  ['read'],
    api_key:  ['read'],
    settings: ['read'],
  },
};
 
// Core permission check function
export function can(
  role: OrgRole,
  resource: Resource,
  action: Action
): boolean {
  return PERMISSIONS[role][resource]?.includes(action) ?? false;
}
 
// React Hook version for components
export function usePermission(role: OrgRole | null | undefined) {
  return {
    can: (resource: Resource, action: Action) =>
      role ? can(role, resource, action) : false,
    isOwner: role === 'owner',
    isAdmin: role === 'admin' || role === 'owner',
    isMember: !!role,
  };
}

Centralizing Auth Checks in Server Actions

Use a higher-order function to enforce permissions consistently across all Server Actions:

// src/lib/auth-guard.ts
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';
import { can, OrgRole, Resource, Action } from '@/types/rbac';
 
export interface AuthContext {
  userId: string;
  orgId: string;
  role: OrgRole;
}
 
// Auth guard with built-in permission check
export async function withOrgAuth<T>(
  orgId: string,
  resource: Resource,
  action: Action,
  handler: (ctx: AuthContext) => Promise<T>
): Promise<T> {
  const cookieStore = await cookies();
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { cookies: { getAll: () => cookieStore.getAll() } }
  );
 
  const { data: { user }, error: authError } = await supabase.auth.getUser();
  if (authError || !user) {
    throw new Error('Unauthorized: Please sign in');
  }
 
  // Fetch membership and role
  const { data: membership, error: memberError } = await supabase
    .from('organization_members')
    .select('role')
    .eq('organization_id', orgId)
    .eq('user_id', user.id)
    .not('accepted_at', 'is', null)
    .single();
 
  if (memberError || !membership) {
    throw new Error('Forbidden: You are not a member of this organization');
  }
 
  const role = membership.role as OrgRole;
 
  if (!can(role, resource, action)) {
    throw new Error(`Forbidden: ${role} cannot ${action} ${resource}`);
  }
 
  return handler({ userId: user.id, orgId, role });
}
 
// Example usage in a Server Action
export async function deleteProject(orgId: string, projectId: string) {
  'use server';
 
  return withOrgAuth(orgId, 'project', 'delete', async ({ userId }) => {
    const supabase = /* server client */;
 
    const { error } = await supabase
      .from('projects')
      .delete()
      .eq('id', projectId)
      .eq('organization_id', orgId);
 
    if (error) throw error;
 
    return { success: true };
  });
}

Permission-Driven UI

// src/components/ProjectActions.tsx
'use client';
 
import { usePermission } from '@/types/rbac';
import type { OrgRole } from '@/types/rbac';
 
interface ProjectActionsProps {
  projectId: string;
  orgId: string;
  currentUserRole: OrgRole;
  onDelete: () => void;
}
 
export function ProjectActions({
  projectId,
  orgId,
  currentUserRole,
  onDelete,
}: ProjectActionsProps) {
  const { can } = usePermission(currentUserRole);
 
  return (
    <div className="flex gap-2">
      {can('project', 'update') && (
        <button className="btn-secondary">Edit</button>
      )}
      {can('project', 'delete') && (
        <button className="btn-danger" onClick={onDelete}>
          Delete
        </button>
      )}
    </div>
  );
}

Step 4: Stripe Metered Billing Implementation

The code in this step assumes the legacy Usage Records API. Current Stripe has replaced it with Billing Meters — the diff and the migration path are covered later in "From Usage Records to Billing Meters." Get the whole picture here first, then head there.

Usage-based pricing is a powerful differentiator for SaaS products. Stripe's Metered Billing lets you charge customers based on actual API call volume or AI token consumption each month.

Prompt for Antigravity's agent:

Help me implement Stripe Metered Billing.
Requirements:
- Usage-based plan: $2 per 1,000 API calls
- Monthly limits per plan (Free: 1,000 calls, Starter: 10,000 calls)
- Real-time usage tracking
- Automated monthly billing

Setting Up Stripe Products and Prices

// scripts/setup-stripe-products.ts
import Stripe from 'stripe';
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
 
async function setupMeteredBilling() {
  // Create the product
  const product = await stripe.products.create({
    name: 'SaaS API Usage',
    description: 'Pay per API call',
  });
 
  // Create the metered price
  const price = await stripe.prices.create({
    product: product.id,
    currency: 'usd',
    recurring: {
      interval: 'month',
      usage_type: 'metered',      // key: metered billing
      aggregate_usage: 'sum',     // sum usage across the month
    },
    unit_amount: 2,               // $0.02 per unit
    transform_quantity: {
      divide_by: 1000,            // 1,000 calls = 1 unit ($0.02)
      round: 'up',
    },
  });
 
  console.log('Price ID:', price.id);  // set this in .env
}

Recording API Usage

// src/app/api/usage/record/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
 
export async function POST(req: NextRequest) {
  try {
    const { orgId, endpoint, tokensUsed } = await req.json();
 
    const supabase = /* server client */;
 
    const { data: org, error } = await supabase
      .from('organizations')
      .select('stripe_subscription_id, plan, api_usage_this_month')
      .eq('id', orgId)
      .single();
 
    if (error || !org) {
      return NextResponse.json({ error: 'Organization not found' }, { status: 404 });
    }
 
    // Enforce free plan limits
    if (org.plan === 'free' && org.api_usage_this_month >= 1000) {
      return NextResponse.json(
        { error: 'Monthly limit reached. Please upgrade your plan.' },
        { status: 429 }
      );
    }
 
    // Report usage to Stripe (the core of metered billing)
    if (org.stripe_subscription_id && org.plan !== 'free') {
      const subscription = await stripe.subscriptions.retrieve(
        org.stripe_subscription_id
      );
      const subscriptionItem = subscription.items.data[0];
 
      await stripe.subscriptionItems.createUsageRecord(
        subscriptionItem.id,
        {
          quantity: Math.ceil(tokensUsed / 100),
          timestamp: Math.floor(Date.now() / 1000),
          action: 'increment',
        }
      );
    }
 
    // Log usage to Supabase
    await supabase.from('api_usage_logs').insert({
      organization_id: orgId,
      user_id: (await supabase.auth.getUser()).data.user?.id,
      endpoint,
      tokens_used: tokensUsed,
    });
 
    // Increment the monthly counter
    await supabase
      .from('organizations')
      .update({ api_usage_this_month: org.api_usage_this_month + 1 })
      .eq('id', orgId);
 
    return NextResponse.json({ success: true });
  } catch (error) {
    console.error('Usage recording error:', error);
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

Stripe Webhook for Subscription Lifecycle

// src/app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import { createServiceRoleClient } from '@/lib/supabase-service';
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
 
export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get('stripe-signature')!;
 
  let event: Stripe.Event;
 
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
  } catch (err) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }
 
  const supabase = createServiceRoleClient(); // bypasses RLS for admin ops
 
  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated': {
      const subscription = event.data.object as Stripe.Subscription;
      const customerId = subscription.customer as string;
      const plan = getPlanFromPriceId(subscription.items.data[0].price.id);
 
      await supabase
        .from('organizations')
        .update({
          stripe_subscription_id: subscription.id,
          plan,
          updated_at: new Date().toISOString(),
        })
        .eq('stripe_customer_id', customerId);
      break;
    }
 
    case 'invoice.payment_succeeded': {
      const invoice = event.data.object as Stripe.Invoice;
 
      // Reset monthly usage counter on successful payment
      await supabase
        .from('organizations')
        .update({ api_usage_this_month: 0 })
        .eq('stripe_customer_id', invoice.customer as string);
      break;
    }
 
    case 'customer.subscription.deleted': {
      const subscription = event.data.object as Stripe.Subscription;
 
      // Downgrade to free plan
      await supabase
        .from('organizations')
        .update({ plan: 'free', stripe_subscription_id: null })
        .eq('stripe_subscription_id', subscription.id);
      break;
    }
  }
 
  return NextResponse.json({ received: true });
}
 
function getPlanFromPriceId(priceId: string): string {
  const planMap: Record<string, string> = {
    [process.env.STRIPE_STARTER_PRICE_ID!]: 'starter',
    [process.env.STRIPE_PRO_PRICE_ID!]: 'pro',
    [process.env.STRIPE_ENTERPRISE_PRICE_ID!]: 'enterprise',
  };
  return planMap[priceId] ?? 'free';
}

Step 5: Tenant Onboarding Flow

Automate the journey from organization creation to active subscription:

// src/app/actions/onboarding.ts
'use server';
 
import Stripe from 'stripe';
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
 
export async function createOrganization(formData: FormData) {
  const name = formData.get('name') as string;
  const slug = formData.get('slug') as string;
  const plan = formData.get('plan') as string;
 
  const supabase = createServerClient(/* ... */);
 
  const { data: { user }, error: authError } = await supabase.auth.getUser();
  if (authError || !user) redirect('/signin');
 
  // Check slug uniqueness
  const { data: existing } = await supabase
    .from('organizations')
    .select('id')
    .eq('slug', slug)
    .single();
 
  if (existing) {
    return { error: 'This slug is already taken.' };
  }
 
  // Create Stripe customer
  const customer = await stripe.customers.create({
    email: user.email!,
    name,
    metadata: { org_slug: slug },
  });
 
  // Create organization (starts on free plan)
  const { data: org, error: orgError } = await supabase
    .from('organizations')
    .insert({
      name,
      slug,
      plan: 'free',
      stripe_customer_id: customer.id,
    })
    .select()
    .single();
 
  if (orgError) {
    return { error: 'Failed to create organization.' };
  }
 
  // Add creator as owner
  await supabase.from('organization_members').insert({
    organization_id: org.id,
    user_id: user.id,
    role: 'owner',
    accepted_at: new Date().toISOString(),
  });
 
  // Redirect to Stripe Checkout if a paid plan was selected
  if (plan !== 'free') {
    const priceId = getPriceId(plan);
    const session = await stripe.checkout.sessions.create({
      customer: customer.id,
      mode: 'subscription',
      line_items: [{ price: priceId, quantity: 1 }],
      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard/${slug}?setup=success`,
      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/onboarding?canceled=true`,
      metadata: { org_id: org.id },
    });
 
    redirect(session.url!);
  }
 
  redirect(`/dashboard/${slug}`);
}

Step 6: Usage Dashboard for Tenants

Give your tenants visibility into their consumption in real time:

// src/app/dashboard/[slug]/billing/page.tsx
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';
 
export default async function BillingPage({
  params,
}: {
  params: { slug: string };
}) {
  const supabase = createServerClient(/* ... */);
 
  const { data: org } = await supabase
    .from('organizations')
    .select('*')
    .eq('slug', params.slug)
    .single();
 
  if (!org) return <div>Not found</div>;
 
  const planLimits: Record<string, number> = {
    free: 1000,
    starter: 10000,
    pro: 100000,
    enterprise: Infinity,
  };
 
  const limit = planLimits[org.plan] ?? 1000;
  const current = org.api_usage_this_month;
  const percentage = limit === Infinity ? 0 : Math.round((current / limit) * 100);
 
  return (
    <div className="p-6 space-y-6">
      <h1 className="text-2xl font-bold">Usage & Billing</h1>
 
      <div className="bg-white rounded-lg p-6 shadow-sm border">
        <h2 className="text-lg font-semibold mb-4">This Month's API Usage</h2>
        <div className="flex justify-between text-sm text-gray-600 mb-2">
          <span>{current.toLocaleString()} calls</span>
          <span>
            {limit === Infinity ? 'Unlimited' : `${limit.toLocaleString()} call limit`}
          </span>
        </div>
        <div className="w-full bg-gray-200 rounded-full h-3">
          <div
            className={`h-3 rounded-full transition-all ${
              percentage >= 90 ? 'bg-red-500' :
              percentage >= 70 ? 'bg-yellow-500' : 'bg-green-500'
            }`}
            style={{ width: `${Math.min(percentage, 100)}%` }}
          />
        </div>
        {percentage >= 80 && (
          <p className="mt-2 text-sm text-amber-600">
            ⚠️ You've used {percentage}% of your monthly limit.
          </p>
        )}
      </div>
 
      <div className="bg-white rounded-lg p-6 shadow-sm border">
        <h2 className="text-lg font-semibold mb-2">Current Plan</h2>
        <p className="text-3xl font-bold capitalize">{org.plan}</p>
        {org.plan === 'free' && (
          <a
            href={`/dashboard/${params.slug}/billing/upgrade`}
            className="mt-4 inline-block px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition"
          >
            Upgrade Plan
          </a>
        )}
      </div>
    </div>
  );
}

Step 7: Production Operations and Testing

Testing for Cross-Tenant Data Leaks

Have Antigravity generate RLS isolation tests to validate your security boundary:

// tests/rls-isolation.test.ts
import { createClient } from '@supabase/supabase-js';
 
describe('RLS Tenant Isolation', () => {
  test("tenant1 user cannot read tenant2's projects", async () => {
    const client1 = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
    await client1.auth.signInWithPassword({ email: 'user@tenant1.com', password: 'test1234' });
 
    const { data, error } = await client1
      .from('projects')
      .select('*')
      .eq('organization_id', TENANT2_ORG_ID);
 
    // RLS returns an empty array — not an error
    expect(data).toHaveLength(0);
    expect(error).toBeNull();
  });
 
  test('member-role user cannot delete a project', async () => {
    const memberClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
    await memberClient.auth.signInWithPassword({
      email: 'member@tenant1.com',
      password: 'test1234',
    });
 
    const { error } = await memberClient
      .from('projects')
      .delete()
      .eq('id', EXISTING_PROJECT_ID);
 
    expect(error).not.toBeNull();
  });
});

Using Antigravity's Planning Mode for Schema Migrations

As your product grows and schema changes become necessary, leverage Antigravity's Planning Mode:

Antigravity Planning Mode prompt:

I want to add a permissions field (JSONB) to organization_members
to support custom per-user permissions within a tenant.

Scope of impact:
1. Database migration
2. Updated RLS policies
3. Permission check logic in auth-guard.ts
4. Type definitions
5. Frontend UI

Please create a phased implementation plan.

Step 8: Team Invitation Flow

A complete multi-tenant SaaS needs a seamless way for owners and admins to invite new members. Here's a production-ready invitation system using Supabase and email notifications.

Invitation Table Schema

-- invitations table (tracks pending invites)
CREATE TABLE organization_invitations (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
  email           TEXT NOT NULL,
  role            TEXT NOT NULL CHECK (role IN ('admin', 'member')),
  invited_by      UUID NOT NULL REFERENCES auth.users(id),
  token           TEXT NOT NULL UNIQUE DEFAULT encode(gen_random_bytes(32), 'hex'),
  expires_at      TIMESTAMPTZ NOT NULL DEFAULT (NOW() + INTERVAL '7 days'),
  accepted_at     TIMESTAMPTZ,
  created_at      TIMESTAMPTZ DEFAULT NOW()
);
 
CREATE INDEX idx_invitations_token ON organization_invitations(token);
CREATE INDEX idx_invitations_email ON organization_invitations(email);
 
ALTER TABLE organization_invitations ENABLE ROW LEVEL SECURITY;
 
-- Only org admins and owners can see and create invitations
CREATE POLICY "invitations_select_policy" ON organization_invitations
  FOR SELECT
  USING (auth.get_org_role(organization_id) IN ('owner', 'admin'));
 
CREATE POLICY "invitations_insert_policy" ON organization_invitations
  FOR INSERT
  WITH CHECK (
    auth.get_org_role(organization_id) IN ('owner', 'admin')
    AND invited_by = auth.uid()
  );

Sending Invitations (Server Action)

// src/app/actions/invite.ts
'use server';
 
import { withOrgAuth } from '@/lib/auth-guard';
import { Resend } from 'resend';
 
const resend = new Resend(process.env.RESEND_API_KEY!);
 
export async function inviteMember(
  orgId: string,
  orgName: string,
  email: string,
  role: 'admin' | 'member'
) {
  return withOrgAuth(orgId, 'member', 'invite', async ({ userId }) => {
    const supabase = /* server client */;
 
    // Check for existing active invite
    const { data: existingInvite } = await supabase
      .from('organization_invitations')
      .select('id, expires_at')
      .eq('organization_id', orgId)
      .eq('email', email)
      .is('accepted_at', null)
      .gt('expires_at', new Date().toISOString())
      .single();
 
    if (existingInvite) {
      return { error: 'An active invitation already exists for this email.' };
    }
 
    // Create the invitation record
    const { data: invitation, error } = await supabase
      .from('organization_invitations')
      .insert({
        organization_id: orgId,
        email,
        role,
        invited_by: userId,
      })
      .select('token')
      .single();
 
    if (error) throw error;
 
    // Send invitation email via Resend
    const inviteUrl = `${process.env.NEXT_PUBLIC_APP_URL}/invite/${invitation.token}`;
 
    await resend.emails.send({
      from: 'noreply@yoursaas.com',
      to: email,
      subject: `You've been invited to join ${orgName}`,
      html: `
        <p>You've been invited to join <strong>${orgName}</strong> as a ${role}.</p>
        <p><a href="${inviteUrl}">Accept Invitation</a></p>
        <p>This invitation expires in 7 days.</p>
      `,
    });
 
    return { success: true };
  });
}

Accepting Invitations

// src/app/invite/[token]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createServerClient } from '@supabase/ssr';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';
 
export async function GET(
  req: NextRequest,
  { params }: { params: { token: string } }
) {
  const cookieStore = await cookies();
  const supabase = createServerClient(/* ... */);
 
  // Validate the token
  const { data: invitation, error } = await supabase
    .from('organization_invitations')
    .select(`
      *,
      organizations(slug, name)
    `)
    .eq('token', params.token)
    .is('accepted_at', null)
    .gt('expires_at', new Date().toISOString())
    .single();
 
  if (error || !invitation) {
    redirect('/invite/expired');
  }
 
  const { data: { user } } = await supabase.auth.getUser();
 
  // If the user isn't signed in, redirect to sign up with the token preserved
  if (!user) {
    redirect(`/signup?invite=${params.token}`);
  }
 
  // Add user to the organization
  const { error: memberError } = await supabase
    .from('organization_members')
    .insert({
      organization_id: invitation.organization_id,
      user_id: user.id,
      role: invitation.role,
      invited_by: invitation.invited_by,
      accepted_at: new Date().toISOString(),
    });
 
  if (memberError) {
    // Handle case where user is already a member
    if (memberError.code === '23505') {
      redirect(`/dashboard/${invitation.organizations.slug}`);
    }
    redirect('/invite/error');
  }
 
  // Mark invitation as accepted
  await supabase
    .from('organization_invitations')
    .update({ accepted_at: new Date().toISOString() })
    .eq('token', params.token);
 
  redirect(`/dashboard/${invitation.organizations.slug}?joined=true`);
}

Step 9: Per-Tenant API Key Management

Many SaaS products need to issue API keys to tenants so they can integrate with your service programmatically. Here's a secure implementation:

-- api_keys table
CREATE TABLE api_keys (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
  name            TEXT NOT NULL,
  key_prefix      TEXT NOT NULL,         -- first 8 chars, for display (e.g. "sk_live_")
  key_hash        TEXT NOT NULL UNIQUE,  -- bcrypt hash of the full key
  created_by      UUID NOT NULL REFERENCES auth.users(id),
  last_used_at    TIMESTAMPTZ,
  expires_at      TIMESTAMPTZ,           -- NULL = never expires
  created_at      TIMESTAMPTZ DEFAULT NOW()
);
 
ALTER TABLE api_keys ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "api_keys_select" ON api_keys
  FOR SELECT USING (auth.is_org_member(organization_id));
 
CREATE POLICY "api_keys_insert" ON api_keys
  FOR INSERT WITH CHECK (
    auth.get_org_role(organization_id) IN ('owner', 'admin')
    AND created_by = auth.uid()
  );
 
CREATE POLICY "api_keys_delete" ON api_keys
  FOR DELETE USING (
    auth.get_org_role(organization_id) IN ('owner', 'admin')
  );

// src/app/actions/api-keys.ts
'use server';
 
import { withOrgAuth } from '@/lib/auth-guard';
import { hash } from 'bcryptjs';
import { randomBytes } from 'crypto';
 
function generateApiKey(): { fullKey: string; prefix: string } {
  const secret = randomBytes(32).toString('base64url');
  const fullKey = `sk_live_${secret}`;
  return { fullKey, prefix: fullKey.substring(0, 12) };
}
 
export async function createApiKey(
  orgId: string,
  name: string,
  expiresInDays?: number
) {
  return withOrgAuth(orgId, 'api_key', 'create', async ({ userId }) => {
    const supabase = /* server client */;
    const { fullKey, prefix } = generateApiKey();
 
    // Hash the key before storing — never store raw keys
    const keyHash = await hash(fullKey, 12);
 
    const expiresAt = expiresInDays
      ? new Date(Date.now() + expiresInDays * 86400 * 1000).toISOString()
      : null;
 
    const { data, error } = await supabase
      .from('api_keys')
      .insert({
        organization_id: orgId,
        name,
        key_prefix: prefix,
        key_hash: keyHash,
        created_by: userId,
        expires_at: expiresAt,
      })
      .select('id, key_prefix, name, created_at, expires_at')
      .single();
 
    if (error) throw error;
 
    // Return the full key ONCE — it can never be retrieved again
    return { ...data, fullKey };
  });
}

The critical security principle here: store only the hash, return the plaintext key only once at creation time. This mirrors how services like GitHub and Stripe handle API keys.

From Usage Records to Billing Meters: The Metered Billing API Changed Generations

The stripe.subscriptionItems.createUsageRecord() call used in Step 4 belongs to the legacy metered billing API. Stripe removed that family of endpoints in the Basil API version (2025-03-31), and Billing Meters is now the single entry point for usage-based billing.

I found this out the blunt way: I carried this implementation into a project, bumped the SDK, and watched the type disappear from my editor. Code that worked simply stopped existing at a version boundary. Since metered billing feeds directly into what customers get charged, I'd write anything new on Billing Meters from day one.

The migration is really a shift in framing. Instead of "increment a quantity on a subscription item," you "send a usage event for a customer and let Stripe do the aggregation." Once that clicks, the code actually gets shorter.

Create the meter once

A meter belongs to a metric, not to a subscription. You can create one in the dashboard, but I keep it in code so staging and production stay identical.

// Run once during setup — use the same event_name across environments
const meter = await stripe.billing.meters.create({
  display_name: 'API Requests',
  event_name: 'api_requests',
  default_aggregation: { formula: 'sum' },
  customer_mapping: {
    type: 'by_id',
    event_payload_key: 'stripe_customer_id',
  },
  value_settings: { event_payload_key: 'value' },
});
 
// Keep meter.id — you'll pass it as recurring.meter when creating prices

event_name cannot be changed later. Pick a granularity like api_requests that still means the same thing three plans from now.

Rewrite the usage call

Here is the Step 4 recording endpoint, before and after.

// ❌ Before: this method no longer exists on Basil and later
const subscription = await stripe.subscriptions.retrieve(org.stripe_subscription_id);
await stripe.subscriptionItems.createUsageRecord(
  subscription.items.data[0].id,
  { quantity: Math.ceil(tokensUsed / 100), action: 'increment' }
);
 
// ✅ After: send an event for the customer
await stripe.billing.meterEvents.create({
  event_name: 'api_requests',
  payload: {
    stripe_customer_id: org.stripe_customer_id,
    value: String(Math.ceil(tokensUsed / 100)), // payload values are strings
  },
  identifier: `usage_${orgId}_${endpoint}_${requestId}`,
  timestamp: Math.floor(Date.now() / 1000),
});

Look closely at identifier. The idempotency key we hand-rolled in Pitfall 2 is now a first-class part of the API — events sharing an identifier are deduplicated over a rolling window of at least 24 hours. The double-counting guard just got one layer thicker.

Keep the UNIQUE constraint in your own database anyway. A replay that arrives past the rolling window still gets through. The two-layer defense idea survives the migration intact.

There's a quieter win too. The old path required a subscriptions.retrieve() round trip for every single usage event. Billing Meters only needs the customer ID, so that round trip disappears entirely — and the recording endpoint got noticeably faster from that one change alone.

Rewrite the dashboard aggregation

Step 6's usage display needs the same treatment.

// ❌ Before
const usageRecord = await stripe.subscriptionItems.listUsageRecordSummaries(
  subscription.items.data[0].id,
  { limit: 1 }
);
const stripeUsage = usageRecord.data[0]?.total_usage ?? 0;
 
// ✅ After: aggregate per meter over an explicit window
const summaries = await stripe.billing.meters.listEventSummaries(METER_ID, {
  customer: org.stripe_customer_id,
  start_time: periodStart,   // the subscription item's current_period_start
  end_time: Math.floor(Date.now() / 1000),
});
const stripeUsage = summaries.data.reduce((sum, s) => sum + s.aggregated_value, 0);

One caveat: listEventSummaries lags event submission by a few minutes. Wire it straight into a live counter and users will read it as "I used it, and nothing moved."

The two-layer model from Step 6 — own counter for the UI, Stripe as the source of truth for billing — turns out to be the answer here as well. Because those roles were already separated, this migration only touched two places: the recording endpoint and the aggregation query.

Old and new, side by side

Purpose	Usage Records (pre-2025-03-31)	Billing Meters (current)
Report usage	`subscriptionItems.createUsageRecord()`	`billing.meterEvents.create()`
Read aggregates	`subscriptionItems.listUsageRecordSummaries()`	`billing.meters.listEventSummaries()`
Reporting unit	Subscription item	Customer (`stripe_customer_id`)
Idempotency	Your own `idempotencyKey` only	`identifier`, built in (24h+ window)
Usage before a subscription	Not possible	Possible — useful for trial metering
Freshness	Near-immediate	A few minutes of lag

If you already have a legacy integration, Stripe's migration guide for legacy usage-based billing covers moving prices and subscriptions across. Knowing up front that the price objects migrate before your code does makes the sequencing much less painful.

One more field that disappeared in the same release

Basil also removed current_period_start and current_period_end from the subscription resource and moved them onto subscription items.

// ❌ Before
const periodStart = subscription.current_period_start;
 
// ✅ After: read the billing period from the item
const periodStart = subscription.items.data[0].current_period_start;

Later in this article I argue that billing decisions should key off the period start. This is where that value now lives. Miss it during migration and your aggregation window silently starts at undefined, quietly widening to all time. No error, no alert — which is exactly what makes it nasty.

What the Docs Don't Tell You: Lessons From Production

Everything above is code that works. This section is about the problems that only surface once real billing traffic flows through it. I learned these by running Stripe memberships (a monthly Pro plan and a lifetime Premium license) across four sites in Dolice Labs — issues invisible at design time that show up only in production.

Pitfall 1: `auth.uid()` inside an RLS policy is re-evaluated per row

The RLS policies from Step 2 are correct, but once a table grew past tens of thousands of rows the dashboard suddenly slowed to a crawl. The cause: auth.uid() inside the policy is re-evaluated for every row. PostgreSQL's planner doesn't treat it as stable, so it calls the function on each row scan.

The fix is to wrap the call in a subquery so it evaluates once.

-- ❌ Before: auth.uid() evaluated per row (measured 470ms / 50k rows)
CREATE POLICY "members can read projects"
ON projects FOR SELECT
USING (
  organization_id IN (
    SELECT organization_id FROM organization_members
    WHERE user_id = auth.uid()
  )
);
 
-- ✅ After: (SELECT auth.uid()) becomes an initplan, evaluated once (measured 8ms, same data)
CREATE POLICY "members can read projects"
ON projects FOR SELECT
USING (
  organization_id IN (
    SELECT organization_id FROM organization_members
    WHERE user_id = (SELECT auth.uid())
  )
);

Just wrapping it as (SELECT auth.uid()) took the same tenant filter on 50k rows from 470ms down to 8ms — roughly a 60x improvement. Supabase later added this to their performance guide, but the introductory RLS tutorials don't mention it. I lost a whole evening to it, chasing a missing index that wasn't the problem.

Pitfall 2: Stripe metered billing quietly double-counts

The usage-recording API from Step 4 can send the same usage to Stripe twice — on retries, double-clicks, or cross-region replays on Vercel. Because metered billing increments (action: 'increment'), a duplicate send inflates the bill directly, and you won't notice unless you read the logs.

The fix is to issue an idempotency key per usage event and reject duplicates on both Stripe's side and your own DB.

// Attach a stable idempotency key to each usage event
const idempotencyKey = `usage_${orgId}_${endpoint}_${requestId}`;
 
// 1) Try recording in your own DB first; a UNIQUE constraint rejects duplicates
const { error: dupErr } = await supabase
  .from('api_usage_logs')
  .insert({ organization_id: orgId, request_id: requestId, /* ... */ });
if (dupErr?.code === '23505') {
  // Already recorded. Don't send to Stripe; succeed idempotently.
  return NextResponse.json({ success: true, deduped: true });
}
 
// 2) Pass the same idempotencyKey to Stripe (defense in depth)
await stripe.subscriptionItems.createUsageRecord(
  subscriptionItem.id,
  { quantity: Math.ceil(tokensUsed / 100), action: 'increment' },
  { idempotencyKey }
);

Add a UNIQUE constraint on request_id in api_usage_logs, and pass idempotencyKey as the third argument to the Stripe SDK. After this two-layer guard, my monthly billing discrepancy dropped to zero. Stripe's idempotency keys expire after 24 hours, so the DB UNIQUE constraint is your last line of defense.

Pitfall 3: Tying the monthly reset to `invoice.payment_succeeded` drifts by a day

The Step 4 webhook resets api_usage_this_month on invoice.payment_succeeded, but that depends on when payment settles. Payment retries or bank-side delays shifted the reset hours — sometimes a full day — past the billing boundary. To the user, it looks like "it's the first of the month but last month's counter is still there."

In practice, base the usage decision itself on the billing period start (current_period_start). Note that on the current API this field lives on the subscription item (subscription.items.data[0].current_period_start), not on the subscription. Instead of relying on a reset event, aggregate api_usage_logs from current_period_start onward and payment delays no longer matter. I eventually settled on a two-layer model: the counter is a cache for fast UI rendering, while the billing decision is always the period-based aggregate as the source of truth.

Production checklist

Before going live, confirm at least these.

Have you replaced every auth.uid() in RLS policies with (SELECT auth.uid())?
Are there indexes on organization_id and every RLS filter column?
Does the usage-recording API have both an idempotency key and a UNIQUE constraint?
Is the billing decision a period-based aggregate (not dependent on a counter reset)?
Does customer.subscription.deleted immediately downgrade the plan and gate features?
Have you scoped exactly where the service-role webhook bypasses RLS?

Items 1 and 3 are the kind of bugs that keep working while the numbers quietly drift. When you build solo, the month-end statement is sometimes the only place a billing anomaly ever surfaces. That is exactly why I walk through these six items by hand before every production push.

Summary

Building multi-tenant SaaS from scratch is genuinely complex, but Antigravity's agent capabilities dramatically cut the time spent on trial and error — from schema design to RLS policy generation to Stripe integration code.

The three pillars of this guide:

Supabase RLS — automatic tenant isolation at the database layer; protects against application-layer bugs
Stripe Metered Billing — charge based on actual usage, making revenue grow naturally with your customers
RBAC — type-safe authorization that protects both Server Actions and UI from unauthorized access

To go deeper: explore Building on Antigravity and Supabase — Auth, RLS, Edge Functions, and Policy Performance for advanced Supabase patterns, and Building a SaaS Payment System with Stripe × Antigravity — Full-Stack Implementation for end-to-end payment flow implementation.

One closing thought. What paid off most here was not the architecture itself, but deciding early where billing correctness would live. The counter serves the screen; the aggregate serves the invoice. Keep those roles apart and even a full API generation change only touches a handful of files.

If you take one thing away, start by rewriting your RLS policies in the (SELECT auth.uid()) form. Tenant isolation performance changes shape on that line alone.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

✦Copy-paste ready implementation code
✦New advanced guides published daily
✦$5/mo or $10 for lifetime access

View Membership →