MongoDB Stitch provides a rich layer of abstraction between client applications and a MongoDB database. To ensure that data is exposed correctly to end users of your client applications, all requests from MongoDB Stitch clients require authentication.

To perform authentication, there are various authentication providers that can be integrated into a client application with the Stitch SDKs.

For applications where you want users to be able to view or manipulate data without registering or creating an account, you can use Anonymous Authentication.

For applications where end users create an account or log in with existing credentials, you can use various providers that integrate with existing login services (Facebook and Google), or use providers that allow you or your end users to create new credentials (Email/Password, API Keys, Custom Auth).

Once your end users are authenticated, their Sessions are managed with access tokens and refresh tokens.


When an end user authenticates with a MongoDB Stitch application for the first time, a Stitch user is created. These user entities have various metadata fields that are made available in function context, in rule expansions, and in the SDKs.

Field Type Description Example
id string An ObjectId that uniquely identifies this user. "59dfd08246224caae5369fb7"
type string The type of this user. Will be "normal" for a typical user, or "server" for users authenticated via a server API key generated in the MongoDB Stitch admin console. "normal"
data document Miscellaneous metadata associated with this user. Each authentication provider exposes different types of metadata. Look at the page for each provider for more information.
  "name": "Jane Doe",
  "email": ""
identities array The list of identities associated with this user. Each authentication provider can provide a identity, and users can be associated with multiple idenities.
      "id": "1234567898765432"
      "provider_type": "oauth2-facebook"

When setting up service rules and writing functions, the id field will be the most useful for associating MongoDB documents with particular users. For example, the ToDo Tutorial Web App uses ToDo item documents with an "owner_id" field to associate each ToDo item with a particular user.

The MongoDB Stitch admin console provides an interface for managing existing users, and creating new users with certain authentication providers. For more information, see User Management.

Authentication Providers

For a new user to be created, or for an existing user to log into a MongoDB Stitch app, there must be a mechanism by which that user is authenticated.

The types of authentication mechanisms available to users of a Stitch app are based on the authentication providers enabled in the Providers tab on the Authentication page of the Stitch admin console.

An authentication provider is a service provided by MongoDB Stitch that can create a user or authenticate someone as an existing user in exchange for some credentials

The following is a list of the authentication providers currently available in MongoDB Stitch, as well as the metadata they expose in the data field of users authenticated through them.

Authentication Provider Description Available Metadata
Anonymous Mechanism for authenticating without credentials. None
Email/Password Mechanism for authenticating with an email address and password. Requires implementing scripts with the SDKs for confirming an email and resetting a password. email
Google OAuth2-based mechanism for logging in with an existing Google account. Can be for regular Google accounts, or can be restricted to organizational domains. email, picture, name
Facebook OAuth2-based mechanism for logging in with an existing Facebook account. email, picture, name
Custom Mechanism for logging in with JWT-based credentials generated by a custom-built service separate from MongoDB Stitch. Can be customized in the Stitch admin console.
API Key Mechanism for logging in with API keys generated in the Stitch admin console, or by your end users. name

For more details on a particular provider, see its documentation page.

You can enable just one provider if you want all users to authenticate in the same way, or you can enable multiple providers for more flexibility.

An example of an app that would benefit from multiple authentication providers is a blog or news service. The typical reader of such an app would authenticate anonymously so that they don’t need to register. The blog authors and/or journalists would need to sign in with some other provider to become authorized to publish new content.

Each authentication provider generates an “identity” that is exposed in the identities field of the user. Although not currently available in the MongoDB Stitch Beta, there will eventually be a way to link a user to multiple identities so that a single user will be able log into a Stitch app in multiple ways.


When a user is successfully authenticated, their sessions are managed with access tokens and a refresh token provided by MongoDB Stitch. The client SDKs implement the logic of managing these tokens and providing them to Stitch when making requests, but it can be useful to understand how sessions work when you’re building your client applications.

For web browsers, the JavaScript SDK stores these tokens in HTML5 local storage. In the Android SDK, they are stored in Shared Preferences. In the iOS SDK, they are stored in the Keychain.

The access token for a session expires after thirty minutes. However, a new session can be started by retrieving a new access token from Stitch using the refresh token. The SDKs automatically take care of refreshing access tokens, so you do not need to worry about this when implementing client applications.

When the refresh token expires, which is after sixty days by default, there is no way for the client application to start a new session without re-authenticating. Users will need to sign in again, and in the case of Anonymous Authentication, those users will not be able to re-authenticate unless they have had another identity associated with them.

The different SDKs have different ways of handling an expired refresh token, so be sure to refer to the SDK documentation and source code when building your client application if you want to cleanly handle expired or invalidated refresh tokens.

There are also ways to invalidate a refresh token before the sixty days expiration. Each of the SDKs provides a logout() method for their client, which will locally delete current session information by deleting the current access and refresh token, and it will invalidate the current refresh token on the MongoDB Stitch server.


The logout() method provided by the SDKs does NOT invalidate any active sessions on the server. This means that if an access token is leaked out of storage before logout() is called, that access token can be theoretically used by an attacker to continue making requests on behalf of the user who “logged out” for up to thirty minutes (until that access token/session expires).

The user list under the Users tab on the Authentication page of the MongoDB Stitch admin console also provides a way to revoke all sessions for a particular user. This will invalidate all access tokens and refresh tokens for that user. See the user management page for more information.