Docs Menu

Docs HomeDevelop ApplicationsAtlas Device SDKs

Connect to App Services - Flutter SDK

On this page

  • Before You Begin
  • Access the App Client
  • Advanced Configuration
  • Get App by ID

The App client is the interface to the Atlas App Services backend. It provides access to App Services features like user authentication and Device Sync.

  1. Create an App Services App

  2. Find the App ID in the App Services UI

Changed in version 1.7.0: App must be created on the main isolate.

Create an App instance to access App Services features throughout your client application. We recommend that you create the App instance only once on the main isolate, ideally as soon as the app starts.

  1. Get your App Services App's ID from the App Services UI. To learn how, refer to Find your App ID.

  2. Create an AppConfiguration object with your App's App ID as the argument.

  3. Create an App with the AppConfiguration you just created. In Flutter v1.7.0 and later, this must be done on the main isolate, otherwise the SDK throws an error.

After you create the App, you can access the constructed App instance on a background isolate using App.getById. Refer to the Get App by ID section on this page for more information.

final appConfig = AppConfiguration(APP_ID);
final app = App(appConfig);

You can create multiple App client instances to connect to multiple Apps. All App client instances that share the same App ID use the same underlying connection.


Changing an App Config After Initializing the App

Changed in version 1.8.0: baseUrl is not cached in the AppConfiguration

When you initialize the App client, the configuration is cached internally. Attempting to close and then re-open an App with a changed configuration within the same process has no effect. The client continues to use the cached configuration.

In Flutter SDK version 1.8.0 and later, the baseUrl is no longer cached in the App configuration. This means that you can change the baseUrl, and the App client will use the updated configuration. In earlier SDK versions, changes to the baseUrl in a cached App configuration have no effect.

Deprecated since version 1.6.0: App.localAppName and App.localAppVersion are no longer used.

You can add optional arguments to the AppConfiguration for more granular control of your App client. You may want to add things like custom timeouts for connections or keys for local metadata encryption. To learn about the available configuration options, refer to the AppConfiguration reference documentation.

final appConfig = AppConfiguration(APP_ID,
defaultRequestTimeout: const Duration(seconds: 120)
// ... see reference docs for all available configuration options


Connect Using Android 7 or Older

The default HTTP client included with the Realm Flutter SDK does not work for apps running on Android 7 or older. To work around this, you must add a custom HTTP client to your AppConfiguration. To learn more, refer to Connect to App Services Using Android 7 or Older.

New in version 1.7.0.

After you have created an App instance on the main isolate, you can access the constructed instance on a background isolate by passing the App ID to the App.getById() method. Then, you can use it to work with the App and users as needed.

// Create an App instance once on main isolate,
// ideally as soon as the app starts
final appConfig = AppConfiguration(APP_ID);
final app = App(appConfig);
final appId =;
final receivePort = ReceivePort();
// Later, access the App instance on background isolate
await Isolate.spawn((List<Object> args) async {
final sendPort = args[0] as SendPort;
final appId = args[1] as String;
try {
final backgroundApp = App.getById(appId);
// ... Access App users
final user = backgroundApp?.currentUser!;
// Use the App and user as needed.
sendPort.send('Background task completed');
} catch (e) {
sendPort.send('Error: $e');
}, [receivePort.sendPort, appId]);
← Application Services Overview - Flutter SDK