Authenticate Users - Flutter SDK

On this page

Before You Begin

Register a New User Account
Log In
Anonymous User
Email/Password User
Custom JWT User
API Key User
Custom Function User
Facebook User
Google User
Apple User
Log a User Out
Retrieve Current User

Atlas App Services provides an API for authenticating users using any enabled authentication provider. Instantiate a Credentials object and pass it to App.logIn() to authenticate and create a User object for that user. Each authentication provider corresponds to a static constructor method used to instantiate Credentials objects for that authentication provider.

Before You Begin

Create an App Services App.
Enable and configure one or more App Services authentication providers.

Register a New User Account

Realm registers accounts differently depending on the authentication provider:

You do not need to register anonymous users.
To register an email/password user, refer to Email/Password User Registration.
If you are using Google, Facebook, Apple, or Custom JWT authentication, registration is handled by these third-party services.

Log In

You can authenticate users with App.logIn().

If successful, app.logIn returns a User object.

Anonymous User

The anonymous authentication provider enables users to log in to your application with short-term accounts that store no persistent personal information. To log in with anonymous authentication, create an anonymous credential by calling Credentials.anonymous() and then pass the generated credential to app.logIn.

final anonCredentials = Credentials.anonymous();
await app.logIn(anonCredentials);

If you want more than one anonymous user, set reuseCredentials: false when creating additional anonymous credentials.

final anonUser = await app.logIn(Credentials.anonymous());
final otherAnonUser =
    await app.logIn(Credentials.anonymous(reuseCredentials: false));

Email/Password User

The Email/Password authentication provider enables users to log in to your application with an email username and a password. To log in with email/password authentication, create an email/password credential by calling Credentials.emailPassword() with the user's email and password. Then pass the credential to app.logIn.

final emailPwCredentials =
    Credentials.emailPassword("lisa@example.com", "myStr0ngPassw0rd");
await app.logIn(emailPwCredentials);

To learn more about the complete flow of using App Services Email/Password authentication, refer to Email/Password Users.

Custom JWT User

If you have configured the Custom JWT authentication provider, you can log in using JWT credentials from an external authentication provider.

To log in with Custom JWT authentication, create a JWT credential by calling Credentials.jwt() on a JWT string. Then pass the credential to app.logIn.

final token = await authenticateWithExternalSystem();
final jwtCredentials = Credentials.jwt(token);
final currentUser = await app.logIn(jwtCredentials);

API Key User

If you have enabled API Key authentication, you can log in using either a client or server API key.

To log in with API key authentication, create an ApiKey credential by calling Credentials.apiKey() on an API key string. Then pass the credential to app.logIn().

final apiKeyCredentials = Credentials.apiKey(myApiKey);
final apiKeyUser = await app.logIn(apiKeyCredentials);

To generate a server API key to use in your credentials, refer to the Create a Server API Key documentation.

To work with user API keys with the same permissions as the currently logged in user, use the User.apiKeys client. You can create, fetch, delete, disable, and enable user API keys.

// Create user API key
final apiKey = await user.apiKeys.create("api-key-name");
// Get existing user API key by ID
// Returns `null` if no existing API key for the ID
final refetchedApiKey = await user.apiKeys.fetch(apiKey.id);
// Get all API keys for a user
final apiKeys = await user.apiKeys.fetchAll();
// Disable API key
await user.apiKeys.disable(apiKey.id);
// Check if API key is enabled
print(apiKey.isEnabled); // prints `false`
// Enable API key
await user.apiKeys.enable(apiKey.id);
// Delete a user API key
await user.apiKeys.delete(apiKey.id);

Custom Function User

If you have configured the Custom Function authentication provider, you can log in using custom authentication logic handled by an Atlas Function.

To log in with Custom Function authentication, pass a stringified JSON with your custom arguments to Credentials.function(). Then pass the credential to app.logIn.

final credentials = {
  "username": "someUsername",
};
// payload must be a JSON-encoded string
final payload = jsonEncode(credentials);
final customCredentials = Credentials.function(payload);
final currentUser = await app.logIn(customCredentials);

Facebook User

If you have configured the Facebook authentication provider, you can log in using an existing Facebook account.

To log in with Facebook authentication, pass a Facebook access token to Credentials.facebook(). Then pass the credential to app.logIn.

final facebookCredentials = Credentials.facebook(accessToken);
final currentUser = await app.logIn(facebookCredentials);

Important

Do Not Store Facebook Profile Picture URLs

Facebook profile picture URLs include the user's access token to grant permission to the image. To ensure security, do not store a URL that includes a user's access token. Instead, access the URL directly from the user's metadata fields when you need to fetch the image.

Google User

If you have configured the Google authentication provider, you can log in using an existing Google account.

To log in with a Google authentication code, pass a Google authentication code to Credentials.googleAuthCode(). Then pass the credential to app.logIn.

final googleAuthCodeCredentials = Credentials.googleAuthCode(authCode);
final currentUser = await app.logIn(googleAuthCodeCredentials);

To log in with a Google ID token, pass a Google ID token to Credentials.googleIdToken(). Then pass the credential to app.logIn.

final googleIdTokenCredentials = Credentials.googleIdToken(idToken);
final currentUser = await app.logIn(googleIdTokenCredentials);

Apple User

If you have configured the Sign-in with Apple authentication provider, you can log in using an existing Apple account.

To log in with Apple authentication, pass an Apple access token to Credentials.apple(). Then pass the credential to app.logIn.

final appleCredentials = Credentials.apple(idToken);
final currentUser = await app.logIn(appleCredentials);

Tip

If you get a Login failed error saying that the token contains an invalid number of segments, verify that you're passing a UTF-8-encoded string version of the JWT.

Log a User Out

You can log out any user, regardless of the authentication provider used to log in, using User.logOut(). This method:

Deletes locally stored user credentials from the device
Immediately halts any synchronization to and from the user's realms

Because logging out halts synchronization, you should only log out after all local Realm updates have uploaded to the server.

await user.logOut();

Retrieve Current User

Once you have an authenticated user, you can retrieve the User object with the App.currentUser property. The currentUser object is persisted in local storage, so even if the app shuts down after the initial authentication, you do not need to call logIn again (unless the user logged out).

final user = app.currentUser;

← User Management - Flutter SDK Email/Password Users - Flutter SDK →