Docs Menu

Docs HomeAtlas App Services

Enable Custom User Data

On this page

You can store arbitrary data about your application users in a MongoDB collection and configure Atlas App Services to automatically expose each user's data in a field of their user object. For example, you might store a user's preferred language, date of birth, or their local timezone.

App Services automatically finds a user's custom data document and includes it in their access token when they log in. You can access the data in the custom_data field of the user's object in function context, the %%user expansion, and their client application access token.


Because App Services stores the custom user data in the access token in the HTTP header, you should keep the custom user data payload small (say, less than 16KB). Other services might limit the HTTP header size, which means that large custom user data objects can cause integration issues.

App Services does not manage custom user documents so you are responsible for creating and deleting them. The underlying data is a regular MongoDB document, so you can use standard CRUD operations through the MongoDB Atlas service to define and modify a user's custom data. You can also use authentication triggers to dynamically update user documents, such as storing the time of their most recent login in the lastLogin field.


You can access custom user data in the client SDKs as well as functions and rule expressions.


Store One Document Per User

Documents that contain user data must include the user's ID in a specific field. If multiple documents specify the same user's ID, App Services only exposes the data from the document that was inserted first.


Custom Data May Be Stale

App Services does not dynamically update a user's custom data if the underlying document changes. Instead, App Services fetches a new copy of the data whenever a user refreshes their access token, such as when they log in. This may mean that the custom data won't immediately reflect changes, e.g. updates from an authentication Trigger. If the token is not refreshed, App Services waits 30 minutes and then refreshes it on the next call to the backend, so custom user data could be stale for up to 30 minutes plus the time until the next SDK call to the backend occurs.

App Services stores MongoDB documents that correspond to custom user data in a linked MongoDB Atlas cluster. When you configure custom user data for your application, you specify:

  • the custom user data cluster

  • the custom user data database

  • the custom user data collection in which custom user data documents are stored

  • the user ID field used to map custom user data documents to users (via user ID)

Because custom user data belongs to a specific user, it could contain personal or private information depending on the needs of your application. If your application stores such information in custom user data, you should restrict access to custom user data appropriately. While the permissioning model of your custom user data depends on the needs of your application, consider using one of the following permission models to restrict read and write access to privileged users only:

  • Make your custom user data readable and writable by only the user whose ID matches the user ID field of each custom user data document. In this permissioning model, the user writes custom user data to a MongoDB data source either directly to or through Sync.

  • Make your custom user data readable and writable by only a system user in a system function. Create a system function that handles edits to custom user data for a user using the value provided by the function context. In this permissioning model, the user writes custom user data using the Functions API.

←  Find and View a UserEnable User Metadata →
Give Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.