> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/membership/settings/onboarding.md).

# Onboarding

Change how users get into your project — registration, default roles, password rules and reset, invitation and verification emails.

**Where:** Membership → Settings → **Onboarding** · `/projects/<project>/membership/settings#onboarding`

## Before you start

* For the email rows (welcome, password reset, invitation, verification): the Email module is on and has the [templates](/codemash/cloud/emails/templates.md). Turning Email on adds ready templates such as *Onboarding new app user*, *Password reset*, *New user invitation* and *New user verification*.
* The roles you want as defaults exist — see [Roles](/codemash/cloud/membership/roles.md).
* You need the `membership:manage` permission (module settings).

## Steps

1. Open **Settings**. **Onboarding** is the first tab. It has five blocks: **Registration**, **Password settings**, **Invitation via Email**, **Verification via Email** and **Custom fields**.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-c81a0bb3f9201ec23be90442ff234e53d7cf4681%2Fsettings-onboarding-1.png?alt=media" alt="Onboarding tab, Registration block: Allow users to register with usernames, Default user role, Permitted user registration roles, Welcome email template, Guest registers as, Automatically subscribe to news"><figcaption><p>The Registration block.</p></figcaption></figure>
2. In **Registration**, press **Change** next to a row, pick the value in the dialog and press **Submit**. Switches save at once.

   | Setting                                                          | What it does                                                       | Example                   |
   | ---------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
   | Allow users to register with usernames, not just email addresses | Switch: allows username sign-up.                                   | on                        |
   | Default user role                                                | The role a newly registered user gets when no other role is given. | `Authenticated`           |
   | Permitted user registration roles                                | The roles your code may give when it creates a user outside Cloud. | `content-editor`          |
   | Welcome email template                                           | The email a new user gets.                                         | `Onboarding new app user` |
   | Guest registers as                                               | The role a guest user gets.                                        | —                         |
   | Automatically subscribe to news                                  | Switch: new users start subscribed to news.                        | off                       |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-e4d0006eefbc38f27b3f74b637658343973b8389%2Fsettings-onboarding-2.png?alt=media" alt="Dialog Default user role: Please provide the role which will be applied to a newly registered user by default, the list with Authenticated System, Cancel and Submit"><figcaption><p>The <strong>Default user role</strong> dialog.</p></figcaption></figure>
3. In **Password settings**, press **Change** next to **Password complexity**. Set the minimum and maximum for **Length**, **Numbers**, **Uppercase letters**, **Lowercase letters** and **Special characters**, and optionally **Allowed special characters**. The rules apply to registration, password reset and password change. Press **Submit**.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-cd550f4a299632899eacdf6a0f7767a1c2e9adff%2Fsettings-onboarding-3.png?alt=media" alt="Dialog Password complexity with Minimum and Maximum for Length, Numbers, Uppercase letters, Lowercase letters, Special characters and Allowed special characters"><figcaption><p>The <strong>Password complexity</strong> dialog.</p></figcaption></figure>
4. Turn on **Password reset via Email** and set its rows: **Password reset email template** (`Password reset`), **Password reset token expiration (in minutes)** (`60`) and **Password reset callback URL** (`https://app.example.com/reset-password`) — the page the user is sent to after the reset.
5. In **Invitation via Email** and **Verification via Email**, turn on **Enabled** and set the template (`New user invitation`, `New user verification`), the **token expiration (in minutes)** (`1440`, `60`) and the **callback URL**.

## Result

Each change saves at once and shows *Success! Settings saved successfully*.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-3f94a421e07b41dcaa9c647ead90874ca1f6b61a%2Fsettings-onboarding-4.png?alt=media" alt="Registration block after the changes: Default user role Authenticated, Welcome email template Onboarding new app user, and the toast Success! Settings saved successfully"><figcaption><p>Saved.</p></figcaption></figure>

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-65830727bec50a9869edd7b0f847210989cb9150%2Fsettings-onboarding-5.png?alt=media" alt="Password settings after a reload: Password complexity at least 10 characters, Password reset via Email on, template Password reset, expiration 60, callback URL https://app.example.com/reset-password; Invitation via Email Enabled, template New user invitation, expiration 1440"><figcaption><p>Password settings and Invitation via Email after a reload.</p></figcaption></figure>

{% hint style="warning" %}
After a reload, three things do not come back today: **Default user role** shows empty although it is saved (the API returns `userRegistersAsRole: authenticated`), and the **Invitation callback URL** and **Verification callback URL** show `-` — the callback you typed is not kept.
{% endhint %}

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-8821b9d2c653162171bf2d88bef91c2a2bec8074%2Fsettings-onboarding-6.png?alt=media" alt="Invitation via Email after a reload: Invitation callback URL shows a dash"><figcaption><p>The invitation callback after a reload.</p></figcaption></figure>

{% hint style="warning" %}
**Custom fields → Custom schema** is not finished: **Change** opens the dialog *Edit schema* with placeholder text and no editor. Do not press **Submit** in it — the dialog saves into the invitation template setting. Cloud has no screen for custom user fields yet.
{% endhint %}

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-cbd5db435b0a04e4eb9b05ca18add2ae91486a33%2Fsettings-onboarding-8.png?alt=media" alt="Dialog Edit schema with placeholder text and no editor, Cancel and Submit"><figcaption><p>The unfinished <strong>Custom schema</strong> dialog.</p></figcaption></figure>

## Change or remove it later

* **Change** a value again at any time; **Enabled** switches turn an email flow off without losing its values.
* The other tabs: [Authentication](/codemash/cloud/membership/settings/authentication.md) · [Account](/codemash/cloud/membership/settings/account.md) · [Communication](/codemash/cloud/membership/settings/communication.md) · [Advanced](/codemash/cloud/membership/settings/advanced.md).

## Do it from code

```ts
await norbix.hub.membership.updatePasswordComplexity({
  minLength: 10, maxLength: 100, minNumbers: 1, minUpper: 1, minLower: 1,
});
```

```sh
norbix hub membership password complexity update --minLength 10 --maxLength 100 --minNumbers 1 --minUpper 1 --minLower 1
```

The other rows are saved with `updateAuthorizationSettings` (one `setting` per call) and `updateAuthenticationSettings` (`allowUsernames`). The client setup is on the [Membership page](/codemash/cloud/membership.md#use-it-from-code). API: [Update Password Complexity](/codemash/api-reference/membership/settings/update-password-complexity.md) · [Update Authorization Settings](/codemash/api-reference/membership/settings/update-authorization-settings.md) · [Update Authentication Settings](/codemash/api-reference/membership/settings/update-authentication-settings.md)