Docs Menu
Docs Home
/ /
Atlas App Services

Define Custom User Metadata

On this page

  • Overview
  • Custom User Data
  • Create and Manage Custom User Data
  • Secure Custom User Data
  • User Creation Function
  • Enable Custom User Data
  • Access Custom User Data from a Client Application
  • Authentication Provider Metadata
  • Configure Authentication Provider Metadata
  • Access User Metadata from a Client Application

You can associate custom metadata with each user of your App. For example, you might store a user's preferred language, date of birth, or any other information that you want to associate with the user.

You can source the metadata for a user from two sources:

  • A collection in MongoDB Atlas that stores custom user data. You can associate each user with a document in the collection by their user ID. You can store arbitrary data in each document.

  • An authentication provider. If the provider uses JSON Web Tokens, such as Google, Facebook, or a custom provider, you can define metadata fields in the provider configuration that associate data from the user's JWT with their user account.

You can store arbitrary data about your application users in a MongoDB collection. Your App maps each user to a document in the collection by querying a specific field for the user's ID. When a user authenticates, your App looks up the user's data and includes it in their access token.

Consider a user with the ID "63ed2dbe5960df2af7fd216e". If your custom user data collection was set up to store the user's ID in the userId field, the user would map to the following document:

"_id": "63ed2e4fb7f367c92578e526",
"user_id": "63ed2dbe5960df2af7fd216e",
"preferences": {
"preferDarkMode": true
"dateOfBirth": "1989-03-11T00:00:00.000Z"

When you use custom user data, keep the following things in mind:

  • 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.

  • Keep Custom User Data Small: The user's full custom user document is included in their access token. In general, aim to keep custom user data documents small (say, less than 16KB). Other services might limit the HTTP header size, which means that larger custom user data objects can cause integration issues.

  • Custom Data May Be Stale: A user's custom data is sourced from a MongoDB collection but is stored in and read from a user's authentication access token. If a user has a valid access token when the underlying document changes, their custom data in that session does not update until they refresh their access token or re-authenticate.

You are responsible for managing documents in the custom user data collection. Depending on your use case, you may:

  • Automatically create a document for each user when they register for your application using a user creation function. This function runs before the user is issued an access token, so the data you add will be in the access token on their first login.

  • Use an authentication trigger to update a user's custom data when they register or log in and to delete their data if their account is deleted. Triggers run asynchronously and may finish after the user's access token is created.

  • Use a scheduled trigger to periodically update or delete custom user data.

  • Manually create, update, and delete documents in the collection using standard CRUD operations from a Function, a Realm SDK, a MongoDB driver or MongoDB Compass.

If your App's custom user data includes personal or private user information, you should restrict access to the custom user data collection. Consider using one of the following permission models to restrict read and write access to privileged users only:

  • A user may read or write their own custom user data document. Deny read and write access to all other documents.


    The following collection configuration has one role that grants a user read and write access to a document if and only if their ID is contained in the document's user_id field.

    A custom user data collection configuration
    "database": "<Database Name>",
    "collection": "<Collection Name>",
    "roles": [
    "name": "ThisUser",
    "apply_when": { "user_id": "" },
    "insert": false,
    "read": true,
    "write": true,
    "search": false,
    "delete": false
    "filters": []
  • No user may read or write any custom user data documents. Instead, use a system function to manage custom user data on behalf of users.

You can define a Function that runs every time a new user successfully registers but before their new user account is created. If the function throws or otherwise errors, the user account creation fails. This lets you ensure that users always have custom data associated with them once created.

The function receives a user metadata object as its only argument. You can use this create a new custom user data document for the user.

exports = async function onUserCreation(user) {
const customUserDataCollection =
try {
await customUserDataCollection.insertOne({
// Save the user's account ID to your configured user_id_field
// Store any other user data you want
favorite_color: "blue",
} catch (e) {
console.error(`Failed to create custom user data document for user:${}`);
throw e


Once you've configured a user creation function, App Services prevents you from deleting the function. If you want to delete the function, first change your custom user data configuration to use a different user creation function.

For code examples that demonstrate how to access and update custom user data from the client application, see the documentation for the Realm SDKs:

Atlas App Services can read user metadata from authentication providers. Then, App Services exposes each user's data in a field of their user object. For example, you might want to access a user's name, email, birthday, or gender.

You can configure App Services to request metadata with the access token when users log in. You can access that data from the logged-in user's object with a client SDK.

You can define the metadata to request when you configure authentication providers. Specify optional metadata fields that you want to access through the user's account. These metadata fields vary depending on provider.

Metadata fields
  • name

  • first_name

  • last_name

  • picture

  • gender

  • birthday

  • min_age

  • max_age

  • email

  • name

  • first_name

  • last_name

  • picture

  • email

Custom JWT
Any field in the JWT as specified by the Custom JWT provider's metadata fields configuration.


Avoid Stale Authentication Provider Metadata

If a user's metadata is updated after the access token is issued, requests using the previously created access token will not have the newly updated metadata. Their user metadata will update when they refresh their access token or re-authenticate.


Security and Authentication Provider Metadata

Authentication provider metadata can be externally-defined by clients and external authentication providers and should be regarded with caution. You should not rely solely on authentication provider metadata for security-related decisions, such as using this metadata in rule expressions for data access permissions.


Tips for Users with Multiple Linked Authentication Providers

  • To ensure the most up-to-date metadata, users should re-authenticate after switching to a different authentication provider. Failure to do so may result in outdated metadata reflected in the Users table in the UI's App Users page and for requests using authentication providers.

  • If a user switches between authentication providers, it may take up to 30 minutes for metadata to propagate. The request is always guaranteed to have the most up-to-date metadata associated with the authentication provider used.

For code examples that demonstrate how to access user metadata data from the client application, see the documentation for the Realm SDKs:

← Create a User