In most web applications, the user is the most important entity. It's at the center of the data model, which is why this entity is owned by the project. If you are using ROQ One, you can visualize the database schema (e.g., with ➚DbSchema) and see the related tables. Typically, the user is identified by a username, and has a unique email and a hashed password.

However, ROQ Platform needs to be able to access some of the information. For instance, to send an email ROQ Platform needs to know the user's email address and name. For this reason, ROQ Suite contains a synchronization mechanism that is based on events. As you can see, the user entity has a sync field which determines whether the latest change was synchronized successfully.

You can force a re-sync by setting sync=false for one or multiple users.

How it works

If you are building on top of ROQ One, this logic is implemented and working out of the box! However, you can still read this documentation if you wish to customize it or you are just curious about how things work.

Register a new user

There are two steps used to register a new user. First, the user needs to be created on the project side. Second, the user will be synchronized to ROQ Platform.

(1) Create a new user on the project side

To create a new user you can use ROQ One's existing register() mutation or - in case you started without ROQ One - by your own implementation.

(2) Synchronize to ROQ Platform

There are two ways to send the user's data to ROQ Platform: either via event or GraphQL API. When a user logs-in on ROQ One, a USER_LOGIN_SYNC event is published to the queue. This event then gets consumed by the ROQ Platform User service. It contains most of the fields that you have in the user entity, but it always excludes the user's password. If you are implementing your own user registration, you can either replicate the event mechanism or simply use the existing createUser() mutation of ROQ Platform with these parameters:

  • email

  • firstName

  • lastName

  • phone

  • locale - Needs to be in the format "en-US", see ➚W3C recommendation

  • timezone - Neds to be a valid timezone like "Europe/Berlin"

  • active - boolean that indicates if a user was activated

mutation CreateUser($user:UserCreateDto!){
  createUser(user: $user){

Handle confirmation mail

Before a new user is allowed to access the web application the user needs to confirm the email. In ROQ One this is realized with an event of type CONFIRM_EVENT but you can also use the sendMail() mutation as explained here: Mails . If you didn't change it then the related mail-type is called CONFIRM_MAIL

The user receives an email that looks like this:

Password forgotten

Inevitably, some users may forget their password. If this occurs, the password can be retrieved using the RESET_PASSWORD_MAIL event, which will send an email to the user. The actual password reset functionality is implemented in ROQ One as ROQ Platform doesn't hold any email.