Getting StartedFlutter

Flutter & Django Quickstart

This is a quickstart guide to help you integrate Descope with your Flutter & Django application. Follow the steps below to get started.

Include the Descope Flutter Package

Incorporate the Descope Flutter SDK as a dependency. Run the following command:

Terminal
flutter pub add descope

(iOS Only) Set minimum global platform version to 13.0

  1. Navigate to ios/Podfile
  2. Uncomment platform :ios, '11.0'
  3. Set the version to 13.0
Podfile
# Uncomment this line to define a global platform for your project
platform :ios, '13.0' # <-- Change this to 13.0

# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
ENV['COCOAPODS_DISABLE_STATS'] = 'true'

# ...

(Android Only) Set minimum global platform version to 24

  1. Navigate to android/app/build.gradle
  2. Replace minSdkVersion flutter.minSdkVersion with minSdkVersion 24
build.gradle
// ...
android {
    // ...
    defaultConfig {
        // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
        applicationId "com.example.flutter_sample_app"
        // You can update the following values to match your application needs.
        // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration.
        minSdkVersion 24 // <-- Change this to 24
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    // ...
}
// ...

Import the Flutter SDK

Proceed to import the Descope Flutter dependency.

main.dart
import 'package:flutter/material.dart';
import 'package:flutter/cupertino.dart';
import 'package:descope/descope.dart'; // <-- Import the Descope SDK

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        title: 'Descope Flutter Sample App',
        theme: ThemeData(
          colorScheme: ColorScheme.fromSeed(seedColor: Colors.green),
          useMaterial3: true,
        ),
        home: Descope.sessionManager.session?.refreshToken.isExpired == false
            ? const HomeScreen()
            : const WelcomeScreen());
  }
}

class WelcomeScreen extends StatefulWidget {
  const WelcomeScreen({super.key});

  @override
  State<WelcomeScreen> createState() => _WelcomeScreenState();
}

// ...

Initialize Descope with Custom Project ID

Set up Descope in main.dart using the Descope Project ID found on your Descope project page. This is needed to activate the SDK.

Note

Optionally, add the baseUrl parameter if using a custom domain in your Descope project (e.g., https://auth.company.com).

main.dart
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  Descope.setup('__ProjectID__');

  await Descope.sessionManager.loadSession();

  runApp(const MyApp());
}

Define and Host Your Flow

Your Descope console provides customizable, predefined authentication flows which are hosted for you. You can also host the flow yourself. You'll use the url of the hosted flow later in your code. If you are deploying to Web, you can set the flow id and container css in the options here as well. For more on web flows set up, read about it in our SDK README.

main.dart
class WelcomeScreen extends StatefulWidget {
  const WelcomeScreen({super.key});

  @override
  State<WelcomeScreen> createState() => _WelcomeScreenState();
}

class _WelcomeScreenState extends State<WelcomeScreen> {
  Future<void> _startFlow() async {
    try {
      final options = DescopeFlowOptions(
        mobile: DescopeMobileFlowOptions(
            flowUrl: 'https://auth.descope.io/login/__ProjectID__', // <-- Your flow URL
			deepLinkUrl: '<your_deep_link_url>' // <-- Your deep link URL
		),
        web: DescopeWebFlowOptions(
          flowId: 'sign-up-or-in',
          flowContainerCss: {
            "background-color": "antiquewhite",
            "width": "500px",
            "min-height": "300px",
            "margin": "auto",
            "position": "relative",
            "top": "50%",
            "transform": "translateY(-50%)",
            "display": "flex",
            "flex-direction": "column",
            "align-items": "center",
            "justify-content": "center",
            "box-shadow": "0px 0px 10px gray",
          },
        ));
    } catch (e) {
      print('Error: $e');
      return;
    }
  }

(Android Only) Configure App Links, Activity & Routing

For Android (iOS works with just a flow url), follow the instructions in our SDK README to establish App Links, create an Activity, and manage routing.

Launch your Flow

Use the flow 'start' function to initiate authentication with a custom flow (URL from step 6). For Android, add the deep link (URL from step 7).

Note

If you're using Magic Link authentication, additional setup is required as mentioned in our README.

main.dart
class _WelcomeScreenState extends State<WelcomeScreen> {
  Future<void> _startFlow() async {
    try {
      final options = DescopeFlowOptions(
        mobile: DescopeMobileFlowOptions(
            flowUrl: 'https://auth.descope.io/login/__ProjectID__',
			deepLinkUrl: '<your_deep_link_url>'
		),
        web: DescopeWebFlowOptions(
          flowId: 'sign-up-or-in',
          flowContainerCss: {
            "background-color": "antiquewhite",
            "width": "500px",
            "min-height": "300px",
            "margin": "auto",
            "position": "relative",
            "top": "50%",
            "transform": "translateY(-50%)",
            "display": "flex",
            "flex-direction": "column",
            "align-items": "center",
            "justify-content": "center",
            "box-shadow": "0px 0px 10px gray",
          },
        ));

      final authResponse = await Descope.flow.start(options); // <-- Start the flow
      final session = DescopeSession.fromAuthenticationResponse(authResponse);
      Descope.sessionManager.manageSession(session);

      if (!mounted) return;
      Navigator.of(context).push(
        MaterialPageRoute(
          builder: (context) => const HomeScreen(),
        ),
      );
    } catch (e) {
      print('Error: $e');
      return;
    }
  }
}

Leverage Flutter SDK's Session Management Functions

Descope offers the Session Manager to confirm user authentication or access user details like email, userId, etc. Personalize the user experience with:

  • user - Access user attributes (email, name, etc.)
  • logout - Revoke and clear active session
  • refreshToken?.isExpired - Check if the user is authenticated

For more specifics on implementing Session Management, check out our Mobile Session Validation page.

For backend Session Validation, continue reading!

SceneDelegate.swift
class _HomeScreenState extends State<HomeScreen> {
  DescopeUser? user = Descope.sessionManager.session?.user;

  Future<void> _logout() async {
    final refreshJwt = Descope.sessionManager.session?.refreshJwt;
    if (refreshJwt != null) {
      await Descope.auth.logout(refreshJwt);
      Descope.sessionManager.clearSession();
    }

    if (!mounted) return;
    Navigator.of(context).push(MaterialPageRoute(
      builder: (context) => const WelcomeScreen(),
    ));
  }

  @override
  Widget build(BuildContext context) {
    if (user == null) {
      return const Scaffold(
        body: Center(
          child: Text('No user data available'),
        ),
      );
    }
    DescopeUser userInfo = user!;

    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text('Hi, ${userInfo.name}!',
                textAlign: TextAlign.center,
                style: Theme.of(context).textTheme.titleLarge),
            Text('Email: ${userInfo.email}'),
            Text('Phone: ${userInfo.phone}'),
            const SizedBox(height: 20),
            CupertinoButton(
              color: Theme.of(context).primaryColorDark,
              onPressed: _logout,
              child: const Text('Log out'),
            )
          ],
        ),
      ),
    );
  }
}

Install Backend SDK

Install the SDK with the following command:

Terminal
pip install django-descope

Import and Setup Backend SDK

You'll need install and setup all of the packages from the SDK. This is done by ensuring django_descope is under INSTALLED_APPS in settings.py.

If you're using a custom domain with your Descope project, make sure to export the Base URL (e.g. export DESCOPE_BASE_URI="https://api.descope.com") when initializing descope_client.

Optionally, to make the Descope username populate from a custom claim instead of sub, set the DESCOPE_USERNAME_CLAIM to the corresponding username claim in the JWT.

settings.py
INSTALLED_APPS = [
  ...
  'django_descope',
]
DESCOPE_PROJECT_ID=os.getenv("DESCOPE_PROJECT_ID")
DESCOPE_USERNAME_CLAIM=os.getenv("DESCOPE_USERNAME_CLAIM")

Add Descope Middleware

Ensure Descope Middleware is after the AuthenticationMiddleware and SessionMiddleware.

settings.py
MIDDLEWARE = [
  ...
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  ...
  'django_descope.middleware.DescopeMiddleware',
]

Configure URLconf

You will then need to include the Descope URLconf in your project urls.py like this.

urls.py
path('auth/', include('django_descope.urls')),

Configure URLconf

The session validation is handled in the Django SDK, through the middleware.

settings.py
INSTALLED_APPS = [
  ...
  'django_descope',
]
MIDDLEWARE = [
  ...
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  ...
  'django_descope.middleware.DescopeMiddleware',
]
DESCOPE_PROJECT_ID=os.getenv("DESCOPE_PROJECT_ID")

Congratulations

Now that you've got the authentication down, go focus on building out the rest of your app!

Here is a sample application using the Django SDK.

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Customize

Now that you have the end-to-end application working, you can choose to configure and personalize many different areas of Descope, including your brand, style, custom user authentication journeys, etc. We recommend starting with customizing your user-facing screens, such as signup and login.

Customize

ArrowRight
Was this helpful?
SparklesAsk AI about this pageArrowRight

Ruby

Learn how to integrate Descope with your Flutter & Ruby in your application.

PHP

Learn how to integrate Descope with your Flutter & PHP in your application.

On this page

Flutter & Django QuickstartCustomize