Vlge Authentication overview (for Admins)
How sign-in works in Vlge
When an owner or board member signs in, they enter an email address and choose a method: password, email verification code, text message code, or passkey (if set up). Vlge does not run its own password or SMS system for that step. Sign-in is handled by AWS Cognito, our identity provider. After Cognito confirms who they are, Vlge loads their account, organization, and permissions.
From an admin perspective, the important parts are:
Login email - The email the person uses at sign-in must match the primary email on their Vlge user record (the one tied to their Cognito account).
Verification methods - Email and SMS codes are sent by Cognito to addresses and numbers on that Cognito account, not necessarily whatever appears on a roster or import sheet. Since the Cognito account is created by your original entry this should match.
Account setup - Many residents are created by import or invite before they ever sign in. Until they complete invite setup (password, terms), they may exist in People but not be fully set up for every sign-in method.
If sign-in fails or codes seem to go to the “wrong” place, the cause is usually one of those three - not a random bug in the portal.
Sign-in: secondary emails, SMS codes, and what admins should know
The problem owners report
If a user reports that verification texts went to “the wrong number” (they see the last 4 digits that are unrecognizable)
Scenario | What the owner experienced | What was actually happening |
Wrong email at sign-in | Entered a secondary address, chose SMS, saw a number ending in digits that looked "wrong" | Cognito has no account for that email. Anti-enumeration returned a fake "masked" destination - not a real send |
Correct email, roster phone in Cognito | Signed in with the right email, chose SMS, code went to an old/imported roster cell | Import/admin provisioning had stored the roster phone in Cognito and marked it verified without the owner confirming it |
Both felt like “the system sent my code to someone else’s number.” Only the second case could actually deliver SMS to a wrong real number.
Why Cognito behaves this way (security)
Cognito (and most auth systems) use account enumeration protection. Without it, an attacker could try emails and learn which ones have accounts - a common recon step before phishing or credential stuffing.
With this security protection enabled, Cognito does not clearly say “this email doesn’t exist.” For unknown emails it may still return sign-in steps that look normal, including SMS OTP with a masked destination that is not tied to any real user. This is why a user might think the text went to the wrong place.
Important for admins:
The masked number (e.g.
***-6198) on a non-existent or mismatched email is not read from your roster and is not proof that Vlge “has the wrong phone on file.”It is Cognito’s way of not revealing whether that email is actually registered.
Codes for those stub flows do not complete sign-in - the owner needs the correct login email or another factor (email OTP, password).
That protects privacy - but it also confuses owners who type a secondary email and assume the displayed digits are “their” number in the system.
How Vlge stores emails vs. what Cognito uses
Each person has:
Field | Purpose |
Primary email ( | Login identity - the only email Cognito knows |
Secondary email ( | Extra contact for comms/imports - not a Cognito login alias by default |
Common pattern:
Invite or import uses one address (e.g.
[email protected]).Roster/import stores it as secondary; primary is another address (e.g.
[email protected]).Owner signs in with the address they remember (Gmail).
Cognito doesn’t recognize it → enumeration stub → misleading SMS "mask".
Admin takeaway: Invites from People are always sent to the person's primary email - the same address they should use to sign in. If sign-in fails, the issue is usually not "wrong invite address," but the owner typing a different address (often a secondary email on their profile) or not having finished account setup.
☎️ Mobile phone: account setup, verification, and SMS sign-in
Vlge handles mobile numbers in three separate steps. They are easy to mix up because all involve a phone number, but only one of them is “sign in with a text message.”
🔗 Account setup (invite link)
When an owner completes their invite link, they set a password and enter a mobile phone on that form. That screen is account setup, not the regular sign-in page.
On setup:
Whatever they enter is saved as their Mobile phone in People.
The same number is copied to their authentication account (AWS Cognito).
The number is stored as not yet verified for login purposes.
No SMS login code is sent during setup. They are not choosing “text me a code” on that screen.
If the form was pre-filled from the roster and they change it before submitting, we save the number they submitted, not the old roster value.
Admin note: Invites from People are always sent to the person’s primary email (the Email field on their record). That is the same address they should use to sign in.
🙋🏽 Phone verification (after they are logged in)
Before an owner should rely on text-message sign-in, they need to verify their mobile in My Profile.
That flow:
Sends a 6-digit code by text to the mobile on their profile (via Vlge, not the sign-in page).
After they enter the code correctly, the number is marked verified for authentication.
SMS sign-in on the login page can then use that verified number.
This step exists so we do not treat a roster or typed number as proof someone controls that phone for login.
Admin note: A mobile on the roster or in People is a contact field. It is not automatically trusted for text-message login until the owner completes verification in Profile (or enters and submits it during setup, then verifies after first login).
📲 SMS sign-in (regular login page)
When an owner goes to Sign in and chooses text message (or similar):
There is no field to type a phone number on that screen.
The code is sent to the mobile already on their authentication account - the same one synced from People / setup / My Profile.
There is no opportunity to change the number here at this phase. To do so they would need to visit My Profile after logging in with their established method (email/pw)
If they have not verified their mobile in Profile, text-message sign-in may be unavailable or unreliable. In that case, use email verification code or password (after they have finished account setup).
After people import or “Add person”
When residents are added by import or Add person (with an invite):
Roster mobile is stored on the person record in People.
If an authentication account is created for them, that mobile may be copied into Cognito as unverified.
Vlge does not automatically mark imported roster phones as "verified" for login.
Text-message sign-in should not be expected to work until the owner has finished account setup and verified their mobile in Profile.
Until then, direct them to their invite link (primary email) and email verification code or password - not SMS sign-in.
Common owner reports (quick admin read)
“The code went to the wrong number.”
Confirm they used their primary email at sign-in, not a secondary email on their profile.
Confirm they finished account setup (invite link).
Check Mobile phone in People matches the number they actually use.
Ask whether they have verified that number in Profile if they are using text-message sign-in.
“I typed my correct number on setup - why didn’t SMS work?”
Setup saves the number; it does not complete verification. They still need to verify in Profile (or use email/password to get in first).
What we changed to improve the experience (6/30)
1. Secondary email resolution at sign-in
Before any Cognito call, if the typed address matches User.additionalEmail, we resolve to the primary login email and use that for authentication.
2. Clear in-app message
If they entered a secondary address, they see something like:
Your account is registered under [email protected]. We'll use that email to sign you in."
Then the method picker (password, email code, SMS, passkey) reflects the real account.
3. Stop auto-verifying import phones
New Cognito users created via import/admin provisioning get roster phones stored as unverified. SMS login for those numbers only works after the owner confirms the number (profile phone verification flow). This reduces the risk of owners having the wrong phone or a phone they do not expect in their account.
These changes do not remove Cognito’s enumeration protection; they reduce how often owners hit the stub by using the wrong email, and they stop roster numbers from being treated as verified login phones on day one.
Recommended admin playbook
When an owner says “the code went to the wrong number”:
Confirm which email they used at sign-in - primary vs. secondary/additional.
In People, check primary email - that is the sign-in address.
If they used a secondary email - have them sign in with primary, or use email verification code on the correct address after our fix (or after deploy).
Compare mobile in People to what they expect - if roster is wrong, update Mobile phone in their profile; they should verify it in Profile → phone verification if they want SMS login.
If they haven’t finished invite setup - resend invite; they must complete setup and set password on the invite link.
What to tell owners (short):
Sign in with the primary email on your account (ask the office if unsure).
If you have two emails on file, the one you sign in with may differ from the one on the invite.
Prefer email verification code if you’re unsure which email is registered.
To use text message codes, add/confirm your mobile in Profile after you’re logged in.
What not to assume:
A masked number shown during sign-in is not always “the number we have on file” - especially if they used the wrong email.
Fixing roster phone in People does not instantly fix SMS login until Cognito has that number and the owner has verified it (or an admin update syncs it and they complete verification).
Quick reference
Owner action | Expected result (after fix) |
Sign in with primary email | Normal method picker; SMS mask matches verified phone on account (if any) |
Sign in with secondary email only | App remaps to primary + explanation message |
Sign in with wrong/unknown email | Cognito may still show generic/fake SMS UI; sign-in will not succeed until correct email |
Complete invite with their mobile | Profile + Cognito updated; SMS still requires phone verification for login |
Import-only user, never completed invite | Should use invite link or primary email + password/email OTP; roster SMS not trusted until verified |