Docs Menu

Docs HomeAtlas Device SDK

Atlas GraphQL API

On this page

  • Prerequisites
  • Set Up GraphQL Client
  • Get Your App ID and GraphQL Endpoint
  • Install a GraphQL Client Package
  • Import dependencies
  • Instantiate an App Services Client & Log In a User
  • Instantiate a GraphQL Client
  • Run Queries and Mutations
  • Run a Query
  • Run a Mutation

You can query your data in MongoDB Atlas from your client app using the Atlas GraphQL API and the Realm Flutter SDK. You can use any standard GraphQL client to query the Atlas GraphQL API.

  1. Create an App Services App

  2. Generate a schema and enable schema rules for the GraphQL API

  3. Install the Realm Flutter SDK


Once you've completed the all the necessary actions in the Prerequisites section above, you must find your App ID and GraphQL endpoint.

You can find both of these in your App's UI on Atlas:

  • To find your App ID, refer to Find Your App ID.

  • To find your GraphQL Endpoint in the Atlas UI, navigate to the GraphQL page. Near the top of the page, you can copy the GraphQL Endpoint link.


Install a standard GraphQL client. This page uses graphql, a lightweight GraphQL client that you can use in Dart standalone and Flutter apps.

flutter pub add graphql

If you haven't already installed the Realm SDK, you can do so now as well.

flutter pub add realm

While the examples on this page use graphql to query the Atlas GraphQL API, there are other Dart and Flutter GraphQL packages that you could use. For example, the graphql_flutter package includes Flutter widget wrappers around the graphql library to provide a more idiomatic Flutter development experience and reduce the need for writing boilerplate code.


Import the realm and graphql packages into your Flutter app. This example also imports the dart:async library to help refresh the access token used in the GraphQL queries.

import 'package:graphql/client.dart';
import 'package:realm/realm.dart';
import "dart:async"; // used to refresh access token

Instantiate the App Services client to connect to the backend. You must log a user in to the App client to authenticate requests to the Atlas GraphQL API with the user's access token. This example also invokes Timer.periodic() to refresh the access token in the background. The access token doesn't refresh automatically.

final app = App(AppConfiguration(YOUR_APP_ID));
await app.logIn(Credentials.anonymous());
// Refresh the user access token every 29 minutes, as the default expiration
// time for an access token is 30 minutes.
Duration(minutes: 29), (_) => app.currentUser?.refreshCustomData());

Now you can use the logged in user's accessToken property to authenticate with the Atlas GraphQL API. To query the GraphQL API as a user, use Bearer token authentication with the user's accessToken.

Use the graphql package to create a GraphQL client to run queries from.

// Build GraphQL endpoint and client
// In the `authLink`, retrieve the accessToken from the app's
// currently logged in user on each request.
// If there's no logged in user, pass an empty string as Bearer token,
// causing the request to fail.
final authLink = AuthLink(
getToken: () => 'Bearer ${app.currentUser?.accessToken ?? ""}',
final link = authLink.concat(HttpLink(YOUR_GRAPHQL_URL));
final client = GraphQLClient(link: link, cache: GraphQLCache());

To learn more about the ways to authenticate requests to the Atlas GraphQL API, refer to Authenticate GraphQL Requests in the App Services documentation.

Run queries and mutations with the Atlas GraphQL API from the client.

To learn more about available operations, refer to the following App Services documentation:

You can also find your entire schema and explore it with test operations in the GraphQL section of the App Services UI.

You can query the Atlas GraphQL API schema with query resolvers generated when you define your schema. To learn more about the generated queries and the inputs they accept, refer to Query Resolvers in the App Services documentation.

final query = """
query {
plants(limit: 5) {
final queryOptions = QueryOptions(
document: gql(query),
final queryRes = await client.query(queryOptions);

You can run mutation against the Atlas GraphQL API schema with mutation resolvers generated when you define your schema. To learn more about the generated mutations and the inputs they accept, refer to Mutation Resolvers in the App Services documentation.

final mutation = """
mutation AddPlant( \$_id: ObjectId!, \$name: String!, \$color: String) {
insertOnePlant(data: {
_id: \$_id
name: \$name
color: \$color
}) {
final mutationOptions = MutationOptions(
document: gql(mutation),
variables: {
'_id': ObjectId().toString(),
'name': 'lily',
'color': 'white'
final mutationRes = await client.mutate(mutationOptions);
←  Connect to App Services - Flutter SDKCall an Atlas Function →