Verified email step

Some sign-in methods give auth4.dev no email address, or one nobody has checked. The verified email step asks those players for an address and a six-digit code on the hosted pages before they return to your app. This guide covers the two settings that control it.

When players are asked

Each browser and game application has its own setting. Open the application's page in the console, find Verified email, choose an option for Require a verified email and select Save email verification. Owners and admins can change it; viewers see it read-only.

Console option	API value	Who is asked
Only when the sign-in method has no email (default)	`when_missing`	Players whose sign-in method gave no email address, or one it hasn't verified, and who haven't verified an address with auth4.dev.
Always	`always`	Every player who signs in with a social account or single sign-on and hasn't verified an address with auth4.dev, even when the provider says its address is verified.
Off	`off`	Nobody. Steam and Epic Games players then have no email address.

An address verified with auth4.dev is one the player proved with an email code, a magic link or a password sign-in, by adding an email address, or through this step. A player who has one is never asked.

Email code, magic link and password sign-ins never see the step: the sign-in itself proves the address.
Passkey and SMS sign-ins, and a reused hosted-login session, are asked only when the player also has a social or single sign-on account. Under the default, that happens only if none of their accounts has a verified address.
Existing players are covered too. Under the default, a Steam or Epic Games player who has no address is asked once, at their next sign-in.
A silent session restore (prompt=none) can't show the step. When the step would apply, the app gets interaction_required and needs an interactive sign-in.

What each sign-in method supplies

Sign-in method	Email address it supplies	Asked under the default?
Email code, magic link, password	The player's address, proven to auth4.dev	Never
Steam	None	Yes
Epic Games	None	Yes
Discord	The account's address and whether Discord verified it, if the account has one	When Discord gives no address or an unverified one
Google	The account's address and whether Google verified it	When Google says the address isn't verified
Apple	An address, which may be a private relay address, and whether Apple verified it	When Apple says the address isn't verified
Microsoft	Sometimes an address, but never whether it is verified	Yes
Enterprise single sign-on	The address the organisation's identity provider sends, verified only at one of the connection's domains	When the address isn't verified
Passkey, SMS	None	Only for players who also have a social or single sign-on account

What the player sees

After the provider, the hosted page shows Add your email and asks for an address.
auth4.dev sends a six-digit code. It works once, for 10 minutes. The player can ask for a new one after 60 seconds, and five wrong codes end it.
With the right code, the player returns to your app signed in, as after any other sign-in.

Use a different sign-in method ends the step and shows the sign-in page again. Nothing is saved and no tokens are issued.
The whole step must finish within 10 minutes of the provider sign-in. After that the player starts signing in again.
You can replace the heading and the paragraph with Add your email heading and Add your email paragraph in the application's page text.

The verified address is saved on the player's account as their email address. Later sign-ins skip the step, and the player can also sign in with an email code to that address. If they remove the address, or you switch the application to Always, the step can appear again at their next sign-in.

When the address already belongs to another player

The second setting is per project. Under Account linking on the project's Settings page, the Link to an existing account after the code is verified switch is off by default. Select Save account linking after changing it. Only owners can change it in the console. In the management API it is linkVerifiedEmail, withnever (off) and after_code (on).

The decision is made only after the player has entered the right code, so nobody learns who uses an address by trying it.

Case	Result
No other player uses the address	The address is added to the player who is signing in. The setting doesn't matter.
Another player uses the address, and linking is off	The page asks the player to use a different address. They can try another one or choose a different sign-in method.
Another player uses the address, linking is on, and the sign-in method was used for the first time in this sign-in	The new sign-in method is added to the player who owns the address, and the player continues as that player. The empty account the first sign-in created is deleted.
Another player uses the address, linking is on, but the sign-in method already belonged to a player before this sign-in	Nothing is moved. The page asks the player to use a different address, as when linking is off.
Another player uses the address, linking is on, but that player is disabled, or already has an account from the same provider	Nothing is moved, and the page asks the player to use a different address.

Existing players' sub values never change. A sign-in method that already belongs to a player is never moved to another one, so the step can't take over an account or split one. Only a brand-new sign-in method can join an existing player, who keeps their own sub.
A link happens only within one sign-in: the new account has had no tokens, sessions or other sign-in methods.
Accounts are never linked by an address the player hasn't proven with a code.

Tokens after the step

With the email scope, the ID token and UserInfo carry the verified address in lower case and email_verified: true.
idp still names the method the player used: a Steam sign-in that passed the step issteam.
sub is the player's usual ID, or the existing player's ID after a link.

The claims are described in Identity claims.

Device approval

The step also runs on the device approval page. After a Steam or other social sign-in there, the player verifies an address and then approves or denies the code as usual. Your game's code doesn't change. Reloading the page during the step starts the step again from the address.

Audit log

Each step writes entries to the project's audit log:

email_step.code_sent when a code is sent;
email_step.verified when the player enters the right code;
email_step.linked when a new sign-in method joins an existing player;
email_step.failed for a wrong or expired code, too many attempts or an address that belongs to another player;
email_step.abandoned when the player chooses another sign-in method.

Entries hold a masked address at most, never the code or the whole address.

Guest upgrades

Guest upgrades run the step too, on the hosted upgrade window and on the upgrade page a native game opens. When a guest links an account the step applies to, such as Steam, the account is linked but the upgrade waits: the player adds an address on the same page, and only then does the game get its new tokens. The guest session keeps working until the step is done, and stays as it is if the player leaves the step or it expires. An address that belongs to another player is refused, whatever linkVerifiedEmail says, because a guest is never merged into another account.

API reference

See the reference for the settings, when the step applies, sending and confirming codes, linking, the claims, device approval and guest upgrades.