API & SDK

Userfront Flutter library

The Userfront Flutter library is in alpha. APIs may change, and functionality is not complete. Some functionality is deliberately more reliant on client implementation than usual, to keep the library flexible during development - usage will be streamlined in the future.

Currently userfront_flutter is focused on enabling mobile sign-on and token refresh, and provides functions to ease usage of the client-to-server API.

The Userfront Flutter library (userfront_flutter) is a Dart library that supports mobile sign-on via Userfront in Flutter and other Dart apps. Mobile sign-on works hand-in-hand with Userfront's Toolkit and Core JS library, as the sign-on flow itself is done in the browser, using your existing web-based sign-on forms.

userfront_flutter uses Dart 3 null safety features.

The Userfront Flutter library is available via pub.dev, the Dart package repository.

The most up-to-date API documentation is always available via pub.dev's auto-generated docs page.

To install the Userfront Flutter, library, run flutter pub add userfront_flutter, or dart pub add userfront_flutter in a non-Flutter app. (While it's aimed at Flutter mobile apps, userfront_flutter uses no Flutter-specific APIs, and would work in a plain Dart context as well.)

#The Userfront class

Userfront authentication is available in Dart/Flutter mobile applications via the Userfront class.

The Userfront class has one async factory, Userfront.init, which takes your workspace or tenant ID and a domain as arguments. The domain is the Web address that requests to Userfront from your Flutter app should "pretend" to be from, for the purpose of treating requests as test mode or live mode requests. To use your Flutter app in live mode, set the domain equal to one of your live domains - set it to anything else, or leave it blank, to use your Flutter app in test mode.

#Authentication

Mobile authentication in a Flutter app consists of three steps:

  1. Start the sign-on by opening a browser tab with an auth URL, which is your existing Userfront web-based sign-on URL with some unique query parameters added.
  2. The user completes the authentication flow in the browser tab, then the Userfront Toolkit or Core JS library deep links back to your Flutter app with an authorization code.
  3. Use the authorization code to finish the sign-on.

The Userfront Flutter library provides methods for the first and third steps.

Once a user is logged in to your mobile app, their JWT access, ID, and refresh tokens are stored securely on the device so they can resume their session later by refreshing their JWT access token.

#createAuthUrl and createAuthUri

The createAuthUrl and createAuthUri methods take a URL you provide, and adds the necessary unique query parameters to it for the Userfront Toolkit or Core JS library to start a mobile authentication session.

createAuthUrl takes and returns a String, while createAuthUri takes and returns a Uri object; they are otherwise identical.

The URL must either embed a signup or login form from your Userfront Toolkit or use the signup() or login() methods from the Userfront Core JS library. This can be the same page you use for your web app's sign-on, or a distinct page (for example, to match your mobile app's branding).

You must call createAuthUrl once for each sign-on. For example, if a user logs in, then logs out, then another user attempts to log in, call createAuthUrl again for the second login attempt.

While you can open the browser tab and handle the returning deep link yourself, you can also use the third-party flutter_web_auth library(opens new window) for this. It implements this flow in a platform-specific way for iOS 11+, macOS 10.15+, Android and Web.

Be sure to view that library's docs for platform-specific setup, to ensure the deep link correctly returns to your mobile app.

While the code examples on this page use flutter_web_auth, it is not required.


To begin the mobile authentication session, open the URL in an in-app browser tab.

#finishAuth

The finishAuth method must be called when returning to your mobile app after the web-based authentication flow is completed.

The in-app browser tab will deep link to your app using a custom scheme, with an authorization_code query parameter attached. Extract this query parameter and pass it to userfront.finishAuth().

You MUST call finishAuth on the same instance of the Userfront app as you called createAuthUrl or createAuthUri on.

This function returns a Map<String, dynamic> which contains the user's JWT access and ID tokens, in the same structure as returned from the Core JS library's signup and login methods.

#logout

The logout method logs the user out by clearing the local copies of the user's JWT access tokens, and if the user had an unexpired session, calling the Userfront API's logout endpoint.

#isLoggedIn

The isLoggedIn property indicates if a user is currently logged in and has an unexpired session.

#Interacting with the Userfront client-to-server API

Once a user is logged in, use the Userfront client-to-server API to work with that user's data.

The Userfront class provides convenience methods to call these API endpoints that automatically attach the user's JWT access token, refreshing it as needed.

  • userfront.api.get()
  • userfront.api.post()
  • userfront.api.put()
  • userfront.api.delete()

There is also a method to refresh the user's JWT access token manually.

  • userfront.refresh() (also callable as userfront.api.refresh())