Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services
/
Authenticate & Manage Users

Read User Metadata

On this page

  • Overview
  • Schema
  • Find Users
  • Filter Users
  • View User Data
  • View a User's Devices
  • View a User's Provider Data
  • View a User's Activity Log
  • Summary

Overview

Atlas App Services represents each application user internally with a User Object that includes a unique ID and additional metadata that describes the user. You can access user objects:

Schema

User objects have the following form:

{
  "id": "<Unique User ID>",
  "type": "<User Type>",
  "data": {
    "<Metadata Field>": <Value>,
    ...
  },
  "custom_data": {
    "<Custom Data Field>": <Value>,
    ...
  },
  "identities": [
    {
      "id": <Unique Identity ID>,
      "provider_type": "<Authentication Provider>",
      "data": {
        "<Metadata Field>": <Value>,
        ...
      }
    }
  ]
}
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 App Services API Key.
"system"
The user is the system user that bypasses all rules.
data
document

A document that contains metadata that describes the user. This field combines the data for all identities associated with the user, so the exact field names and values depend on which authentication providers the user has authenticated with.

Note

System Functions Have No User Data

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

custom_data
document

A document from your application's custom user data collection that specifies the user's ID. You can use the custom user data collection to store arbitrary data about your application's users. If you set the name field, App Services populates the username metadata field with the return value of name. App Services automatically fetches a new copy of the data whenever a user refreshes their access token, such as when they log in. The underlying data is a regular MongoDB document, so you can use standard CRUD operations through the MongoDB Atlas service to define and modify the user's custom data.

Note

Avoid Storing Large Custom User Data

Custom user data is limited to 16MB, the maximum size of a MongoDB document. To avoid hitting this limit, consider storing small and relatively static user data in each custom user data document, such as the user's preferred language or the URL of their avatar image. For data that is large, unbounded, or frequently updated, consider only storing a reference to the data in the custom user document or storing the data with a reference to the user's ID rather than in the custom user document.

identities
array

A list of authentication provider identities associated with the user. When a user first logs in with a specific provider, App Services associates the user with an identity object that contains a unique identifier and additional metadata about the user from the provider. For subsequent logins, App Services refreshes the existing identity data but does not create a new identity. Identity objects have the following form:

{
  "id": "<Unique ID>",
  "provider_type": "<Provider Name>",
  "data": {
    "<Metadata Field>": <Value>,
    ...
  }
}
Field Name
Description
id
A provider-generated string that uniquely identifies this identity
provider_type
The type of authentication provider associated with this identity.
data
Additional metadata from the authentication provider that describes the user. The exact field names and values will vary depending on which authentication providers the user has logged in with. For a provider-specific breakdown of user identity data, see User Metadata.

Note

In general, App Services creates a user object for a given user the first time that they authenticate. If you create a test Email/Password user through the App Services UI, App Services creates that user's user object immediately.

Find Users

To find information about one or more users, click App Users in the left navigation menu. The page opens to the Users tab which has a list of users associated with your Atlas App Services App:

The Users screen in the UI, which shows a filterable list of all users
click to enlarge

Tip

If you already know the ID of the user you want to find, you can search for their ID in the Users table search bar.

To find information about one or more users, call appservices users list. The CLI will prompt you for your App ID and list users in that app for you to select.

appservices users list

You can also specify the arguments when you call the program:

appservices users list --app=<Your App ID>

To find information about one or more users, create a GET request in the following format. You must specify the Group and App ID.

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/users

If you already know the ID of the user you want to find, you can append the ID to the request URL:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/users/<userId>

Tip

See also:

Admin API Documentation

Filter Users

You can specify filters that limit a list of users to a subset of users that satisfy the filter conditions.

Use the filter bar at the top of the Users table to define filters. You can filter by:

  • Provider type

    • Anonymous

    • Email/Password

    • API Key

    • Facebook

    • Google

    • Apple

    • Custom JWT

    • Custom Function

  • Status

    • Confirmed

    • Pending

  • State

    • Enabled

    • Disabled

You can filter user operations with the following flags and arguments:

  • --pending: If included, lists only pending users. Otherwise, lists only confirmed users.

  • --state: Lists only users in the specified state

    • "enabled"

    • "disabled"

  • --provider:

    • "anon-user"

    • "local-userpass"

    • "api-key"

    • "oauth2-facebook"

    • "oauth2-google"

    • "oauth2-apple"

    • "custom-token"

    • "custom-function"

Example

The following command limits the output to only pending (unconfirmed) email/password users:

appservices users list --pending --provider="local-userpass"

Example

The following command limits the output to only disabled users:

appservices users list --state="disabled"

You can filter user operations with the following query parameters:

Parameter
Type
Description
after
string
The id of the last user returned by a previous paginated request.
sort
string
The field name to sort results by. The only valid value is the default: _id.
desc
boolean
If true, returns sorted results in descending order. If not specified or set to false, results return in ascending order.

Example

The following request returns users in descending order by their _id:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/users?desc=true

You can also limit results to only pending (unconfirmed) email/password users. Create a GET request in the following format:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/user_registrations/pending_users

Tip

See also:

Admin API Documentation

View User Data

View a User's Devices

When a user connects to your application, Atlas App Services logs information similar to the following:

A detail view for a specific user that lists devices they've used with your app
click to enlarge

Logged information includes:

  • The device platform, which will be either an http client ("chrome", "firefox", "phantomjs", etc.) or a mobile OS ("ios", "android", etc.)

  • The platform version.

  • Your app version on the device.

  • A unique device ID.

To view this information, from the list of users:

  1. Find the user whose devices you want to view.

  2. Click ... to open the options menu, and select View Devices.

View a User's Provider Data

Whenever a user connects to your application and authenticates using one of the authentication providers you have enabled, App Services logs the provider data.

A detail view for a specific user that lists metadata about them from an authentication provider
click to enlarge

To view this information, from the list of users:

  1. Find the user whose provider data you want to view.

  2. Click ... to open the options menu, and select View Provider Data.

View a User's Activity Log

App Services logs every request made by each of your App users, including executed function calls. Also, if a function writes to the log using console.log, console.warn, or console.error, these entries will be included within the function's log output.

A detail view for a specific user that shows a log of their interactions with your app
click to enlarge

To view this information, from the list of users:

  1. Find the user whose activity data you want to view.

  2. Click View Activity. This redirects you to a log of requests made by that specific user. You can expand an entry to view details for that request.

Summary

  • The user object contains relevant information about the user that you can use in your app logic.

  • The exact information contained in the user object depends on the authentication providers used.

  • You can search for users in the Users page of the App Services UI.

  • App Services logs information such as user's connected devices, provider data, and activity log.

Back

Define User Metadata

Next

Manage User Accounts