Username policy
Logto always enforces a baseline set of username rules: a username contains only letters, numbers, and underscores (_), does NOT start with a number, and is no longer than 128 characters. On top of this baseline, you can configure a username policy to further restrict the usernames end users can choose, such as making usernames case-insensitive, narrowing the length range, or limiting the allowed character types.
Logto applies the username policy in different ways depending on how the username is created or updated:
- End-user flows such as the out-of-the-box sign-in experience, the Account API, and the Account Center always enforce the current username policy. Users see the policy requirements on the username pages and get inline errors when an entered username violates them.
- Administrator actions via the Management API (e.g.,
POST /api/users) are exempt from the policy and only apply the baseline rules, allowing you to provision or migrate users without policy checks when needed.
Updating the policy does not modify or invalidate existing usernames: users keep signing in with their current usernames even if those usernames would no longer be accepted for new registrations.
Set up username policy
To configure the username policy, follow these steps:
- Navigate to the Console > Sign-in & account > Sign-up and sign-in page.
- Under the Advanced options section, click Manage on the Username policy field.
The following settings are available:
- Case sensitive: Whether usernames that differ only by letter case (e.g.,
Aliceandalice) are treated as different usernames. Enabled by default. When disabled, users can sign in with any casing of their username, and new usernames that collide with an existing one case-insensitively are rejected. - Length: Set the minimum and maximum number of characters allowed for the username, within the baseline range of 1 to 128.
- Allowed characters: Choose which character types users can include: uppercase letters
(A-Z), lowercase letters(a-z), numbers(0-9), and underscores(_). At least one of uppercase letters, lowercase letters, or underscores must stay enabled, since the baseline rules don't allow a username to start with a number.
Switch to case-insensitive usernames
Switching an existing tenant from case-sensitive to case-insensitive usernames requires that no two existing usernames collide when compared case-insensitively (e.g., Alice and alice belonging to two different users). While such conflicts exist, saving the policy is rejected with a 409 error.
When you toggle off Case sensitive in the Console, Logto proactively checks for conflicts and lists the colliding usernames so you can resolve them (e.g., by renaming or removing one of the accounts) before saving. You can also query the conflicts directly via GET /api/sign-in-exp/username-policy/case-sensitivity-conflicts.