feat!: rename the gotrue package to supabase_auth

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -23,7 +23,7 @@ body:
       options:
         - supabase_flutter
         - supabase
-        - gotrue
+        - supabase_auth
         - postgrest
         - realtime_client
         - storage_client
@@ -58,10 +58,10 @@ body:
         Output of `flutter doctor -v`, plus the versions of the affected packages.
 
         On Linux/macOS:
-        `dart pub deps | grep -E "supabase|gotrue|postgrest|storage_client|realtime_client|functions_client"`
+        `dart pub deps | grep -E "supabase|postgrest|storage_client|realtime_client|functions_client"`
 
         On Windows:
-        `dart pub deps | findstr "supabase gotrue postgrest storage_client realtime_client functions_client"`
+        `dart pub deps | findstr "supabase postgrest storage_client realtime_client functions_client"`
       render: shell
       placeholder: Flutter, Dart and package versions
     validations:

.github/workflows/label-issues.yml

@@ -21,6 +21,7 @@ jobs:
       label_mappings: |
         {
           "gotrue": "auth",
+          "supabase_auth": "auth",
           "auth": "auth",
           "storage": "storage",
           "storage_client": "storage",

.github/workflows/release-pana.yml

@@ -26,11 +26,11 @@ jobs:
       matrix:
         package:
           - functions_client
-          - gotrue
           - postgrest
           - realtime_client
           - storage_client
           - supabase
+          - supabase_auth
           - supabase_common
           - supabase_flutter
           - supabase_typegen

.github/workflows/test.yml

@@ -64,19 +64,19 @@ jobs:
           echo "Affected packages:"
           echo "$CHANGED"
 
-          DART_PACKAGES="functions_client gotrue postgrest realtime_client storage_client supabase supabase_common supabase_typegen yet_another_json_isolate"
+          DART_PACKAGES="functions_client postgrest realtime_client storage_client supabase supabase_auth supabase_common supabase_typegen yet_another_json_isolate"
 
           entries=()
           for package in $DART_PACKAGES; do
             if ! echo "$CHANGED" | grep -qx "$package"; then
               continue
             fi
             case "$package" in
-              gotrue|postgrest|realtime_client|storage_client|supabase) backend=true ;;
+              postgrest|realtime_client|storage_client|supabase|supabase_auth) backend=true ;;
               *) backend=false ;;
             esac
             case "$package" in
-              gotrue|postgrest|realtime_client|storage_client|supabase) concurrency="1" ;;
+              postgrest|realtime_client|storage_client|supabase|supabase_auth) concurrency="1" ;;
               *) concurrency="0" ;;
             esac
             entries+=("{\"name\":\"$package\",\"backend\":$backend,\"concurrency\":\"$concurrency\"}")
@@ -344,7 +344,7 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           parallel-finished: true
-          carryforward: 'functions_client,gotrue,postgrest,realtime_client,storage_client,supabase,supabase_common,supabase_typegen,yet_another_json_isolate,supabase_flutter'
+          carryforward: 'functions_client,postgrest,realtime_client,storage_client,supabase,supabase_auth,supabase_common,supabase_typegen,yet_another_json_isolate,supabase_flutter'
           fail-on-error: false
 
   test-result:

AGENTS.md

@@ -12,7 +12,7 @@ The repository follows a layered dependency structure:
 
 - **supabase_flutter**: Flutter-specific wrapper with platform integrations (deep links, local storage, app lifecycle)
 - **supabase**: Core Dart client that orchestrates all service clients
-- **gotrue**: Authentication client (sessions, JWT, OAuth)
+- **supabase_auth**: Authentication client (sessions, JWT, OAuth)
 - **postgrest**: Database query client with ORM-style API
 - **realtime_client**: WebSocket client for real-time subscriptions
 - **storage_client**: File storage client with retry logic
@@ -52,9 +52,9 @@ melos format
 
 ### Testing
 
-Most packages have unit tests. The `postgrest`, `gotrue`, `realtime_client`, and `storage_client` packages run against a local Supabase stack started with the Supabase CLI. This requires Docker and the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started) installed.
+Most packages have unit tests. The `postgrest`, `supabase_auth`, `realtime_client`, and `storage_client` packages run against a local Supabase stack started with the Supabase CLI. This requires Docker and the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started) installed.
 
-**For packages requiring a backend (postgrest, gotrue, realtime_client, storage_client):**
+**For packages requiring a backend (postgrest, supabase_auth, realtime_client, storage_client):**
 
 ```bash
 # 1. Start the local Supabase stack from the repository root
@@ -129,7 +129,7 @@ melos version
 
 ### Authentication Flow
 
-- **GoTrueClient** manages sessions, tokens, and JWT validation
+- **AuthClient** manages sessions, tokens, and JWT validation
 - Emits auth state changes via `Stream<AuthState>`
 - **supabase_flutter** adds session persistence via `SharedPreferencesAsync` (mobile) or browser localStorage (web)
 - Deep link handling for OAuth callbacks (detects `?code=` for PKCE or `#access_token=` for implicit flow)
@@ -155,7 +155,7 @@ Example: `supabase.from('users').select('id, name').eq('id', 1).limit(10)`
 ### Error Handling
 
 Each package has its own exception hierarchy:
-- **gotrue**: `AuthException` (base), with specialized subclasses like `AuthApiException`, `AuthRetryableFetchException`
+- **supabase_auth**: `AuthException` (base), with specialized subclasses like `AuthApiException`, `AuthRetryableFetchException`
 - **postgrest**: HTTP-based error responses
 - **realtime**: `RealtimeSubscribeException` with status tracking
 - **storage**: Retry logic with exponential backoff (up to 8 attempts)

MIGRATION.md

@@ -4,7 +4,7 @@ This document describes the breaking changes you need to be aware of when upgrad
 versions of the Supabase Flutter SDK, together with the steps required to migrate your code.
 
 All packages in this repository are released together for a major version, so a single section
-covers `supabase_flutter`, `supabase`, `gotrue`, `postgrest`, `realtime_client`, `storage_client`
+covers `supabase_flutter`, `supabase`, `supabase_auth`, `postgrest`, `realtime_client`, `storage_client`
 and `functions_client`. Every symbol mentioned here is re-exported from `supabase_flutter`, so the
 snippets apply whether you depend on the individual package or on the Flutter one.
 
@@ -14,6 +14,68 @@ snippets apply whether you depend on the individual package or on the Flutter on
 > v3 has not been released yet. This section is updated as breaking changes land on `main`, so
 > treat it as the running list rather than the final one.
 
+### The `gotrue` package is now `supabase_auth`
+
+The service this package talks to has been called Supabase Auth for years, and `gotrue` is a name
+users no longer recognize. The package is published as `supabase_auth` from v3 onwards, and the
+`gotrue` package is discontinued on pub.dev when v3 ships.
+
+If you depend on `supabase_flutter` or `supabase` you do not need to change your dependencies,
+both pull in `supabase_auth` for you and re-export it. You do need to rename the types below.
+
+If you depend on the auth client directly, rename the dependency and the import:
+
+```yaml
+# Before
+dependencies:
+  gotrue: ^2.27.1
+
+# After
+dependencies:
+  supabase_auth: ^3.0.0
+```
+
+```dart
+// Before
+import 'package:gotrue/gotrue.dart';
+
+// After
+import 'package:supabase_auth/supabase_auth.dart';
+```
+
+The types that carried the old name in their own name are renamed to the `Auth` prefix the rest of
+the package already uses:
+
+| Before | After |
+| --- | --- |
+| `GoTrueClient` | `AuthClient` |
+| `GoTrueAdminApi` | `AuthAdminApi` |
+| `GoTrueAdminCustomProvidersApi` | `AuthAdminCustomProvidersApi` |
+| `GoTrueAdminMFAApi` | `AuthAdminMFAApi` |
+| `GoTrueAdminOAuthApi` | `AuthAdminOAuthApi` |
+| `GoTrueAdminPasskeyApi` | `AuthAdminPasskeyApi` |
+| `GoTrueMFAApi` | `AuthMFAApi` |
+| `GoTrueOAuthApi` | `AuthOAuthApi` |
+| `GoTruePasskeyApi` | `AuthPasskeyApi` |
+| `GotrueAsyncStorage` | `AuthAsyncStorage` |
+| `SharedPreferencesGotrueAsyncStorage` | `SharedPreferencesAuthAsyncStorage` |
+
+```dart
+// Before
+final GoTrueClient auth = supabase.auth;
+
+// After
+final AuthClient auth = supabase.auth;
+```
+
+Two extensions `supabase_flutter` adds to the auth client follow the same rename:
+`GoTrueClientSignInProvider` becomes `AuthClientSignInProvider` and `GoTrueClientPasskey` becomes
+`AuthClientPasskey`. You only name these if you were referring to the extension explicitly, for
+example to hide it in an import.
+
+Nothing about the wire format changes. The `X-Client-Info` header still identifies this client as
+`gotrue-dart`, and the `gotrue_meta_security` field in captcha payloads is unchanged.
+
 ### `RealtimeClient.connectionState` is now typed
 
 `RealtimeClient` used to expose the socket state twice: a typed `connState` field and a stringly
@@ -113,15 +175,15 @@ flushed once the join succeeds, so only channels that were never subscribed thro
 ### Plural enum names singularized
 
 A Dart enum type names one value rather than the set, so its name should be singular. Five enums
-were ports of the `realtime-js` and `gotrue-js` names instead, and one more turned up in storage.
+carried plural names instead, and one more turned up in storage.
 Three of them were never reachable from outside the package and are now marked `@internal`; the
 ones below are the renames you can actually hit.
 
 | Before | After | Package |
 | --- | --- | --- |
 | `SocketStates` | `SocketState` | `realtime_client` |
 | `PostgresTypes` | `PostgresType` | `realtime_client` |
-| `AuthenticatorAssuranceLevels` | `AuthenticatorAssuranceLevel` | `gotrue` |
+| `AuthenticatorAssuranceLevels` | `AuthenticatorAssuranceLevel` | `supabase_auth` |
 | `LoadTableSnapshots` | `TableSnapshotScope` | `storage_client` |
 
 No enum values changed, so the only work is renaming the type where you name it explicitly.
@@ -301,9 +363,9 @@ already inert: unused types, options the client ignored, or values the server ne
 
 | Removed | Replacement | Package |
 | --- | --- | --- |
-| `AuthChangeEvent.userDeleted` | none, it was never emitted | `gotrue` |
-| `OAuthProvider.snakeCase` | `OAuthProvider.name` | `gotrue` |
-| `User.confirmedAt` | `User.emailConfirmedAt` | `gotrue` |
+| `AuthChangeEvent.userDeleted` | none, it was never emitted | `supabase_auth` |
+| `OAuthProvider.snakeCase` | `OAuthProvider.name` | `supabase_auth` |
+| `User.confirmedAt` | `User.emailConfirmedAt` | `supabase_auth` |
 | `ReturningOption` | none, it was unused | `postgrest` |
 | `PostgrestClient.auth()` | `PostgrestClient.setAuth()` | `postgrest` |
 | `RealtimeClient.longpollerTimeout` | none, there is no longpoll transport | `realtime_client` |
@@ -461,7 +523,7 @@ replaces them; they only existed to drive the comparison above.
 
 ### The session is persisted with `SharedPreferencesAsync`
 
-`SharedPreferencesLocalStorage` and `SharedPreferencesGotrueAsyncStorage`, the storage
+`SharedPreferencesLocalStorage` and `SharedPreferencesAuthAsyncStorage`, the storage
 implementations `Supabase.initialize` uses by default, wrote through the legacy
 [`SharedPreferences`](https://pub.dev/packages/shared_preferences#sharedpreferences-vs-sharedpreferencesasync-vs-sharedpreferenceswithcache)
 API. They now use `SharedPreferencesAsync`. On web the session still goes into

README.md

@@ -48,7 +48,7 @@ To install on a locally developed app:
 
 ## Testing
 
-The tests for the packages `postgrest`, `gotrue`, `realtime_client` and `storage_client` run against a
+The tests for the packages `postgrest`, `supabase_auth`, `realtime_client` and `storage_client` run against a
 local Supabase stack. To run these tests locally you need `docker` and the
 [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started) installed.
 

packages/supabase/lib/src/supabase_client.dart

@@ -44,7 +44,7 @@ import 'trace_http_client.dart';
 /// Pass an instance of `YAJsonIsolate` to [isolate] to use your own persisted
 /// isolate instance. A new instance will be created if [isolate] is omitted.
 ///
-/// Pass an instance of `GotrueAsyncStorage` to the `pkceAsyncStorage` field of
+/// Pass an instance of `AuthAsyncStorage` to the `pkceAsyncStorage` field of
 /// [authOptions] and set its `authFlowType` field to `AuthFlowType.pkce` in
 /// order to perform auth actions with pkce flow.
 /// {@endtemplate}
@@ -62,9 +62,9 @@ class SupabaseClient {
   final Client? _httpClient;
   late final Client _authHttpClient;
   late final Client _functionsHttpClient;
-  late final Client _gotrueHttpClient;
+  late final Client _authApiHttpClient;
 
-  GoTrueClient? _authInstance;
+  AuthClient? _authInstance;
 
   /// Supabase Functions allows you to deploy and invoke edge functions.
   late final FunctionsClient functions;
@@ -167,10 +167,10 @@ class SupabaseClient {
             supabaseUrl,
           )
         : baseHttpClient;
-    _gotrueHttpClient = tracedHttpClient;
+    _authApiHttpClient = tracedHttpClient;
     _authInstance = _initSupabaseAuthClient(
       autoRefreshToken: authOptions.autoRefreshToken,
-      gotrueAsyncStorage: authOptions.pkceAsyncStorage,
+      authAsyncStorage: authOptions.pkceAsyncStorage,
       authFlowType: authOptions.authFlowType,
     );
     _authHttpClient = AuthHttpClient(
@@ -204,7 +204,7 @@ class SupabaseClient {
     }
   }
 
-  GoTrueClient get auth {
+  AuthClient get auth {
     if (accessToken == null) {
       return _authInstance!;
     }
@@ -317,21 +317,21 @@ class SupabaseClient {
     _authInstance?.dispose();
   }
 
-  GoTrueClient _initSupabaseAuthClient({
+  AuthClient _initSupabaseAuthClient({
     required bool autoRefreshToken,
-    required GotrueAsyncStorage? gotrueAsyncStorage,
+    required AuthAsyncStorage? authAsyncStorage,
     required AuthFlowType authFlowType,
   }) {
     final authHeaders = {...headers};
     authHeaders['apikey'] = _supabaseKey;
     authHeaders['Authorization'] = 'Bearer $_supabaseKey';
 
-    return GoTrueClient(
+    return AuthClient(
       url: _authUrl,
       headers: authHeaders,
       autoRefreshToken: autoRefreshToken,
-      httpClient: _gotrueHttpClient,
-      asyncStorage: gotrueAsyncStorage,
+      httpClient: _authApiHttpClient,
+      asyncStorage: authAsyncStorage,
       flowType: authFlowType,
     );
   }

packages/supabase/lib/src/supabase_client_options.dart

@@ -34,7 +34,7 @@ class PostgrestClientOptions {
 
 class AuthClientOptions {
   final bool autoRefreshToken;
-  final GotrueAsyncStorage? pkceAsyncStorage;
+  final AuthAsyncStorage? pkceAsyncStorage;
   final AuthFlowType authFlowType;
 
   const AuthClientOptions({

packages/supabase/lib/supabase.dart

@@ -4,7 +4,7 @@
 library;
 
 export 'package:functions_client/functions_client.dart';
-export 'package:gotrue/gotrue.dart';
+export 'package:supabase_auth/supabase_auth.dart';
 export 'package:postgrest/postgrest.dart';
 export 'package:realtime_client/realtime_client.dart';
 export 'package:storage_client/storage_client.dart';

packages/supabase/pubspec.yaml

@@ -19,12 +19,12 @@ resolution: workspace
 
 dependencies:
   functions_client: 2.7.1
-  gotrue: 2.27.1
   http: ^1.6.0
   meta: ^1.7.0
   postgrest: 2.9.1
   realtime_client: 2.13.0
   storage_client: 2.8.0
+  supabase_auth: 3.0.0-dev.1
   supabase_common: 0.1.2
   yet_another_json_isolate: 2.1.1
   logging: ^1.3.0

packages/gotrue/README.md → packages/supabase_auth/README.md

@@ -4,7 +4,7 @@
     <img alt="Supabase Logo" width="300" src="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg">
   </a>
 
-  <h1 align="center">gotrue</h1>
+  <h1 align="center">supabase_auth</h1>
 
   <p align="center">
     Dart client library for <a href="https://supabase.com/docs/guides/auth">Supabase Auth</a>.
@@ -19,11 +19,15 @@
 
 <div align="center">
 
-[![pub package](https://img.shields.io/pub/v/gotrue.svg)](https://pub.dev/packages/gotrue)
+[![pub package](https://img.shields.io/pub/v/supabase_auth.svg)](https://pub.dev/packages/supabase_auth)
 [![pub test](https://github.com/supabase/supabase-flutter/workflows/Test/badge.svg)](https://github.com/supabase/supabase-flutter/actions?query=workflow%3ATest)
 
 </div>
 
+> **Note**
+>
+> This package was published as `gotrue` up to and including v2. That package is discontinued in favour of `supabase_auth`.
+
 ## Docs
 
 The docs can be found on the official Supabase website.

packages/gotrue/example/main.dart → packages/supabase_auth/example/main.dart

@@ -1,13 +1,13 @@
 // ignore_for_file: avoid_print
 
-import 'package:gotrue/gotrue.dart';
+import 'package:supabase_auth/supabase_auth.dart';
 
 /// Example to use with Supabase Auth https://supabase.com/
 Future<void> main() async {
-  const gotrueUrl = 'http://localhost:9999';
+  const authUrl = 'http://localhost:9999';
   const supabaseKey = '';
-  final client = GoTrueClient(
-    url: gotrueUrl,
+  final client = AuthClient(
+    url: authUrl,
     headers: {
       'Authorization': 'Bearer $supabaseKey',
       'apikey': supabaseKey,