User management

Mosaic manages users at two levels: a shared identity and profile in the tenant, and an application-specific account for each Mosaic application the user is registered with. Clients within one application use the same application account. See Plan your application structure.

Mosaic maintains one user record for a person within the tenant, identified by a unique, automatically generated user_id. The record holds tenant-level information, such as the user's primary email and phone number. The same record can be associated with multiple applications.

Each application association represents the user's account in that application. It can contain application-specific information, such as external_account_id and custom_app_data. An existing tenant identity does not automatically give the user an account in every application.

You can create a tenant user and register them with an application through the Admin Portal, APIs, or journeys. Authentication flows can also create users when configured to allow it. If the user already exists in the tenant, registering them with another application associates the existing record with that application. See App users.

Depending on your integration use case, you can leverage the following attributes as user identifiers:

The user profile contains general information about the user, such as their name – first, middle, and last name (each limited to 64 characters) – email, phone number, and birthday. Additionally, when a user authenticates with a social network (Google, Apple, etc.), the profile stores their social account details. Some profile details, such as a phone number or email, are verifiable (i.e., can be validated by Mosaic as belonging to the user), while other data (e.g., address, language) doesn't require verification.

General profile information is stored at the tenant level, rather than copied into a separate person record for each application. Tenant-level fields include the user's identifier within your system (external_user_id), custom attributes (custom_user_fields.*), and custom data (custom_data). Application-specific data is stored for the user's account in the relevant application, including external_account_id and custom_app_data. Access to either scope depends on the caller's permissions.

The user profile can be updated and accessed from the Admin Portal, using Journeys, or APIs. In addition, some basic profile information is included in the ID token returned upon successful authentication (see Identity data).

Each Mosaic application has its own user pool. A user must be registered with each application they access, even when their tenant-level record already exists. Registration can be performed by an administrator, an API, or a journey; it does not necessarily require the user to fill in another sign-up form.

To register a user through the API, call Create user with a client access token for the target application. If the user already exists in the tenant but is not associated with that application, the request adds the application association without updating the existing user's other details. Authentication flows that allow user creation can also perform registration during login.

For example, a user registered with a retail application is not automatically registered with a separate fitness application in the same tenant. Registering them with the fitness application associates their existing tenant record with a second application account. In contrast, a website and mobile app represented by clients of the same Mosaic application use the same application account.

You can manage application associations from the Admin Portal or through APIs. See Manage a user's apps.

Application registration, authenticator registration, and login sessions are separate parts of the setup:

• Identifiers and profile: primary email and phone number are tenant-level attributes. Using the same email in two applications does not imply that a password registered in one works in the other.
• Authenticators: passwords and TOTP registrations are scoped to an application; email- and phone-based authenticators use the tenant-level identity. Register and configure the authentication methods required by each application. See How authenticators work.
• Sessions: sharing a tenant record or an application account does not itself sign the user in to another client. For journey-orchestrated browser SSO, session sharing is controlled through SSO client groups and the login journey.

In the user lifecycle, there are several statuses a user might have. A user can be Pending, Active, or Suspended. For when each status is set, how to change it, and how deleting a user differs from removing them from an app, see User lifecycle.

Users can be managed by administrators either in the Admin Portal, or via APIs, or using Journeys. When using the APIs or journeys, you can only manage the users for the specific application identified by the client ID and secret used to authorize the API or journey call. If a Management Application is used, you can manage users across all applications of the tenant. User management includes the ability to create and delete users, update their profiles, assign users to groups and apps, and update their status. For status changes and deletion, see User lifecycle.

To streamline user lifecycle management across Mosaic and third-party apps, consider using Users SCIM APIs.