Implementing Multi-Tenant Authentication Using Supabase in Flutter

Introduction

Multi-tenant authentication enables a single application instance to serve multiple customers (tenants) while keeping user data separate. Supabase offers PostgreSQL row-level security, custom claims in JWTs, and REST endpoints that simplify multi-tenant patterns. In this tutorial, you’ll learn how to configure Supabase for multi-tenancy and implement a Flutter client that handles tenant-specific authentication flows.

Setup & Supabase Tenant Configuration

First, create a Supabase project and enable row-level security (RLS) on your users table. Add a tenant_id column to isolate user records:

• Go to SQL Editor in your Supabase dashboard.

• Run:

ALTER TABLE auth.users
ADD COLUMN

Next, define RLS policies to ensure users can only access rows matching their tenant_id. Example policy for SELECT:

CREATE POLICY "Select own users"
  ON auth.users FOR SELECT
  USING (tenant_id = current_setting('request.jwt.claims.tenant_id'))

Repeat similar policies for INSERT, UPDATE, and DELETE. In your authentication webhook or Supabase Function, inject the tenant_id claim into the JWT after sign-up or sign-in.

Configuring Flutter Project

Add dependencies in pubspec.yaml:

supabase_flutter: ^0.5.0
flutter_dotenv

Load environment variables for your Supabase URL, anon key, and default tenant:

// main.dart
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:supabase_flutter/supabase_flutter.dart';
Future<void> main() async {
  await dotenv.load();
  await Supabase.initialize(
    url: dotenv.env['SUPABASE_URL']!,
    anonKey: dotenv.env['SUPABASE_ANON_KEY']!,
  );
  runApp(const MyApp());
}

In your sign-in and sign-up UI, include a tenant selector dropdown or prefill from user context. Pass the chosen tenant_id to Supabase via custom metadata:

Implementing Authentication Flow

Use Supabase’s auth.signUp and auth.signIn methods with data parameter to send tenant-specific metadata. For example:

final tenantId = 'tenant_123';
final response = await Supabase.instance.client.auth.signUp(
  email: email,
  password: password,
  options: AuthOptions(redirectTo: 'io.app://callback'),
  data: {'tenant_id': tenantId},
);

On the server side (in an Auth webhook or Function), capture this metadata and append it to the JWT claims under request.jwt.claims.tenant_id. Supabase handles token issuance automatically once configured in Dashboard > Authentication > Url Override > External OAuth and Webhooks.

After sign-in, calls to supabase.from('some_table') will automatically include the tenant-specific JWT. RLS policies enforce that only rows belonging to tenant_id are visible.

Handling Tenant Context

In Flutter, you can expose the tenant ID from the session object:

final session = Supabase.instance.client.auth.currentSession;
final tenantId = session?.user?.userMetadata['tenant_id'];

Store this in a provider or state management solution like Riverpod or Provider. When making Supabase queries, confirm the tenant context is loaded before building protected widgets:

Supabase queries automatically use the session’s JWT. For manual HTTP requests, include the apikey header and Authorization: Bearer <jwt>.

Security Best Practices

• Enforce SSL/TLS for all API calls.

• Rotate the anon key periodically and use service_role key only in trusted backends.

• Use ephemeral refresh tokens to limit exposure.

• Monitor RLS policy coverage by attempting unauthorized queries in the SQL editor.

• Log authentication events via Supabase Audit Logs.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

You’ve set up Supabase for multi-tenant user isolation using row-level security and custom JWT claims. On the Flutter side, you configured the client, implemented sign-up and sign-in flows that include tenant metadata, and leveraged Supabase’s session object to maintain tenant context. Following security best practices ensures your app remains secure as you onboard additional tenants.