Email verification before password creation

In this email verification flow, your users will be asked to verify their email addresses before they're prompted to create a password. One benefit of this verification flow is that if the user mistypes their email address (and thus can't verify it), they'll be able to correct their mistake before setting a password.

If you're more interested in a flow where email verification occurs after the user creates a password, see our Email verification after creating a password guide instead.

Stytch's email verification flows are intentionally flexible so that you can choose the combination of products that best fits your use case. In this guide, we'll be using our Email OTP product in order to verify email addresses, but you may choose to use Email Magic Links instead by replacing the below Email OTP endpoints with Email Magic Links endpoints.

Create a Stytch Consumer project via the Stytch Dashboard if you don't have one already. To do so, click on your existing project name in top left corner of the Dashboard, click Create a new project, and then select Consumer authentication.

Copy your project_id and secret from the Test environment tab in the API keys section of the Stytch Dashboard. You'll need to include these values in every backend Stytch API call.

First, prompt your user for their email address, and then send them a verification OTP code using our Log in or create User by email endpoint. Here's an example cURL reqeust:

curl --request POST \
  --url https://test.stytch.com/v1/otps/email/login_or_create \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
  -d '{
    "email": "USER_EMAIL_ADDRESS"
  }'

Save the email_id from the Log in or create User response for use in Step 2.

Once your user submits the one-time passcode from the email that they received, call our Authenticate one-time passcode endpoint with the code and the email_id from Step 1 (known in this next call as the method_id).

Be sure to add a session_duration_minutes parameter so that a new Stytch session is started. We'll use 30 minutes for the purposes of this guide, but feel free to tailor the session length to your own use case:

curl --request POST \
  --url https://test.stytch.com/v1/otps/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
  -d '{
    "method_id": "EMAIL_ID_FROM_STEP_1",
    "code": "ONE_TIME_PASSCODE_FROM_USER",
    "session_duration_minutes": 30
  }'

Save the session_token from the Authenticate one-time passcode response for use in Step 3.

At this point, you'll have a new Stytch User with a verified email address. You'll now need to prompt your user to create a password and add it to the User via our Password reset by existing session endpoint, using the session that was created in Step 2:

curl --request POST \
  --url https://test.stytch.com/v1/passwords/session/reset \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
  -d '{
    "password": "NEW_PASSWORD_FROM_USER",
    "session_token": "SESSION_TOKEN_FROM_STEP_2"
  }'

Note that for security purposes, you'll need to complete this step within 5 minutes of creating the session in Step 2.

Upon receiving a successful Password reset by existing session response, your Passwords signup flow with email verification is complete! You'll have a new Stytch User with both a verified email address and a password that your user will be able to use to authenticate in the future.

Check out our Passwords API reference and our One-time passcodes API reference, which also include sample code for all of our backend SDKs.