Stitch Users


This page covers the technical aspects of how Stitch represents users internally. It describes the structure and content of user objects, which model individual user accounts and are referenced by expressions like context.user and %%user. It also covers the session-based authentication mechanisms that Stitch uses internally, including details on storing, refreshing, and invalidating access tokens.

To learn how to manage your application’s users, check out these guides:

User Objects

For each authenticated user of your application, a Stitch user object is created that contains metadata about that user. Stitch encrypts the user data and stores it securely. You can access the user object from:

An example user object might look like the following:

user : {
  id: "59dfd08246224caae5369fb7",
  type: "normal",
  data: {
        "name": "Jane Doe",
        "email": ""
  identities: [
            "id": "1234567898765432"
            "provider_type": "oauth2-facebook"

The user object contains the following fields:

Field Type Description
id string A string representation of the ObjectId that uniquely identifies the user.
type string The type of the user. The value will be "server" for users authenticated via a server API key generated in the MongoDB Stitch admin console; otherwise, the value will be "normal".
data document

When using the Google or Facebook authentication provider, the data field contains the metadata associated with the user. The following sub-fields are provided by the authentication provider:

  • name
  • email
  • picture
  • first_name
  • last_name
  • gender
  • birthday
  • min_age
  • max_age


The min_age and max_age fields are only provided by the Google authentication provider if you explicitly enable the Google+ APIs.

In addition, Stitch adds the following sub-fields to the data field:

  • creation_date
  • last_authentication_date
  • disabled
identities array The list of identities associated with the user. Each authentication provider can provide an identity, and users can be associated with multiple identities.


If you are using Email/Password Authentication, the user object is created when you add a new account. For all other authentication providers, the user object is created when an end user authenticates for the first time.

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

User Sessions

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.

You can invalidate a refresh token by calling the logout() method on the client, which does two things: it locally deletes current session information by deleting both the access and refresh tokens, and it invalidates the 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 expires).

The user list under the Users tab, on the Users page of the MongoDB Stitch admin console, provides a way to revoke all sessions for a specific user. This will invalidate all access tokens and refresh tokens for that user. See the Revoking User Sessions page for the specific steps.