Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0-quickstart-flutter-windows.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Prerequisites:
  • Flutter SDK 3.24.0+ and Dart 3.5.0+
  • Windows 10 or newer
  • Visual Studio 2022 with Desktop development with C++ workload
  • Auth0 account — sign up free
This feature is in beta (auth0_flutter 2.1.0-beta.1). The API may change before general availability.
This guide walks you through adding login, logout, and user profile display to a Flutter Windows desktop app using the auth0_flutter SDK with OAuth 2.0 Authorization Code Flow + PKCE.

​
Get Started

1

Create a Flutter Windows project

Create a new Flutter project with Windows platform support.
flutter create --platforms=windows my_app
cd my_app
Verify Windows is available:
flutter devices
You should see a Windows desktop device listed.
Run flutter doctor to verify your environment is set up correctly and Visual Studio 2022 with C++ desktop development is detected.
2

Install the Auth0 Flutter SDK

Add the beta version of the SDK that includes Windows support:
flutter pub add auth0_flutter:2.1.0-beta.1
flutter pub add flutter_dotenv
Your pubspec.yaml should include:
The Auth0 Flutter SDK requires Flutter 3.24.0+ and Dart 3.5.0+. The Windows platform additionally requires Visual Studio 2022 with the C++ desktop development workload.
3

Configure Auth0

Create or configure an Auth0 application with the callback URLs required for Windows desktop authentication.
Create a Native application in your Auth0 Dashboard with the following settings:
FieldValue
Allowed Callback URLsauth0flutter://callback
Allowed Logout URLsauth0flutter://callback
Your credentials:
  • Domain: {yourDomain}
  • Client ID: {yourClientId}
The auth0flutter://callback URL is a custom scheme that routes the browser callback back to your desktop application after authentication completes.
4

Configure environment variables

Create a .env file in the root of your project:Add the .env file to your Flutter assets in pubspec.yaml:
Never commit your .env file to version control. Add it to .gitignore.
5

Configure the Windows runner

The Windows authentication flow requires callback plumbing in your app’s runner. The Flutter plugin does not automatically receive protocol-scheme activations from the OS — you must add single-instance enforcement and URI forwarding.Replace the contents of windows/runner/main.cpp:This code:
  • Enforces single-instance via a Windows mutex
  • Captures auth0flutter://callback URIs passed as command-line arguments
  • Forwards URIs from secondary launches to the running instance via a named pipe
  • Sets the PLUGIN_STARTUP_URL environment variable for the Auth0 plugin to read
6

Register the custom URL scheme

Register auth0flutter as a custom URL scheme so Windows routes callback URIs to your app.Create a file windows/url_scheme.reg:Replace C:\path\to\your\app.exe with the actual path to your built executable. During development this is typically:
build\windows\x64\runner\Debug\my_app.exe
Double-click the .reg file to import it into the Windows Registry.
For production distribution, register the custom URL scheme programmatically in your app’s installer (MSIX, Inno Setup, etc.) rather than relying on a .reg file.
Verify the scheme works:Open Command Prompt and run:
start auth0flutter://test
Your app should launch (or come to the foreground if already running).
7

Implement login and logout

Create lib/auth_service.dart to handle Windows authentication:
The Auth0 Flutter Windows SDK does not currently support credential management. You must manually store credentials if you need sessions to persist across app restarts.
8

Show user profile information

Create the main app UI in lib/main.dart:
9

Run your application

Build and run the app:
flutter run -d windows
Expected flow:
  1. App launches with a Log In button
  2. Click Log In → your system browser opens the Auth0 Universal Login page
  3. Complete authentication in the browser
  4. Browser redirects to auth0flutter://callback → your app comes to the foreground
  5. User’s name, email, and profile picture are displayed
Ensure the custom URL scheme is registered (Step 6) before testing. Without it, the browser callback cannot reach your application.
CheckpointYou should now have a fully functional Auth0 login experience in your Flutter Windows application. The app opens the system browser for Auth0 Universal Login, receives the callback via the custom URL scheme, and displays the authenticated user’s profile.

​
Troubleshooting & Advanced Usage

​
Browser opens but app doesn’t receive callback

Symptom: Auth0 login succeeds in browser but the app never receives the credentials.Fix:
  1. Open Registry Editor → HKEY_CURRENT_USER\Software\Classes\auth0flutter\shell\open\command and confirm the path to your .exe
  2. Test with start auth0flutter://test in Command Prompt — your app should launch
  3. Ensure windows/runner/main.cpp includes the pipe server and mutex code
  4. Check that no stale instances are running in Task Manager
  5. Rebuild completely: flutter clean && flutter run -d windows

​
Authentication times out after 5 minutes

Symptom: Login appears to hang and eventually fails.Fix: The app never received the callback URI. Verify:
  1. The registry entry points to the correct executable path
  2. The mutex name auth0flutter_single_instance_mutex is consistent in main.cpp
  3. No firewall or antivirus is blocking the named pipe
  4. Kill all stale instances and rebuild

​
Second app instance launches instead of forwarding URI

Symptom: A new window opens instead of the existing app receiving the callback.Fix:
  1. Kill all running instances in Task Manager
  2. Ensure the mutex name is consistent in main.cpp
  3. Rebuild: flutter clean && flutter run -d windows

​
WindowsWebAuthentication not found

Symptom: Compilation error referencing windowsWebAuthentication.Fix: Ensure your pubspec.yaml specifies the beta version:
dependencies:
  auth0_flutter: 2.1.0-beta.1
Run flutter pub get to update.

​
Callback URL mismatch error

Symptom: Error “redirect_uri_mismatch” from Auth0.Fix:
  1. Verify Allowed Callback URLs in Auth0 Dashboard → Application Settings is exactly auth0flutter://callback
  2. Ensure the appCustomURL parameter in your code matches: 'auth0flutter://callback'
  3. Check for trailing slashes or whitespace
When Auth0 redirects directly to a custom scheme, the browser may show a prompt or leave a blank tab. For a smoother experience, use an intermediary HTTPS server:
  1. Set up a server endpoint (e.g., https://your-app.example.com/callback) that redirects to auth0flutter://callback?code=...&state=...
  2. In Auth0 Dashboard → Application Settings, set Allowed Callback URLs to https://your-app.example.com/callback
  3. Pass both URLs to the login method:
final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  redirectUrl: 'https://your-app.example.com/callback',
);
The server page can display “Redirecting…” and close itself for a cleaner experience.
Request additional scopes or an API audience:
final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  scopes: {'openid', 'profile', 'email', 'read:messages'},
  audience: 'https://your-api.example.com',
);
Configure the API in Auth0 Dashboard → Applications > APIs before using the audience parameter.

​
Next Steps