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 following types are possible:

Type Description
“normal” The user is an application user logged in through an authentication provider other than the API Key provider.
“server” The user is a server process logged in with any type of Stitch API Key.
“system” The user is a system user that bypasses all rules.
data document

A document containing metadata that describes the user. The exact metadata field names and values depend on the authentication providers associated with the user.

Authentication Provider Details
Anonymous Anonymous users are not associated with any metadata.

Email/Password users are associated with the following metadata fields:

Field Description
email The user’s email address.
API Key (Server & User)

API Key users are associated with the following metadata fields:

Field Description
name The name of the API Key.
OAuth 2.0 (Facebook & Google) OAuth 2.0 users are associated with data provided by the authentication service. The exact fields depend on the provider’s Metadata Fields configuration. Users must explicitly grant your application access to the data when they first log in or when you change the provider configuration.
Custom Custom authentication users are associated with data included in the JWT returned from the external authentication system. The exact values that appear in the user object’s data field depend on the provider’s Metadata Fields configuration.


In system functions, the object is empty. Use context.runningAsSystem() to test if the function is running as a system user.

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 To-Do Tutorial uses To-Do item documents with an "owner_id" field to associate each To-Do 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.