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 UI 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.)
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.
Mobile authentication in a Flutter app consists of three steps:
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.
The createAuthUrl and createAuthUri methods take a URL you provide, and adds the necessary unique query parameters to it for the Userfront UI 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 UI 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 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.
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.
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.
The isLoggedIn property indicates if a user is currently logged in and has an unexpired session.
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())