Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Connect to App Services - Flutter SDK

On this page

  • Before You Begin
  • Access the App Client
  • Advanced Configuration
  • Get App by ID
  • Connect to a Specific Server
  • Connect to a Different Server During Runtime

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]);

By default, Atlas Device SDK connects to Atlas using the global baseUrl of In some cases, you may want to connect to a different server:

  • Your App Services App uses local deployment, and you want to connect directly to a local baseUrl in your region. For more information, refer to the Local Deployment App Services documentation.

  • You want to connect to an Edge Server instance. For more information, refer to the Connect to the Edge Server from Atlas Device SDK App Services documentation.

You can specify a baseUrl in the AppConfiguration:

// Specify a baseUrl to connect to a server other than the default
final appConfig =
AppConfiguration(APP_ID, baseUrl: Uri.parse(''));
var app = App(appConfig);

New in version 1.8.0.

Changed in version 2.2.0: updateBaseUrl accepts null value

In some cases, you might want to change the baseUrl while the app is running. For example, you might want to roam between Edge Servers or move from an App Services connection to an Edge Server connection.

To change the baseUrl during runtime, call the experimental app.updateBaseUrl method. You can pass null to reset the baseUrl to the default value.

// Specify a custom baseUrl to connect to.
// In this case, an Edge Server instance running on the device.
final appConfig = AppConfiguration(
baseUrl: Uri.parse('http://localhost:80')
var app = App(appConfig);
// ... log in a user and use the app ...
// Later, change the baseUrl to the default:
await app.updateBaseUrl(null);

This API is experimental and may change in future releases.

If you want to change the baseUrl after you have logged in a user and have opened a synced database, the app must perform a client reset. For more information, refer to Client Reset.

Perform the following in your code:

  1. Pause the Sync session

  2. Update the baseUrl using the app.updateBaseUrl method

  3. Re-authenticate the user to log in using the new baseUrl

  4. Open a synced database pulling data from the new server

Both the server and the client must be online for the user to authenticate and connect to the new server. If the server is not online or the client does not have a network connection, the user cannot authenticate and open the database.

← Application Services Overview - Flutter SDK