/
Contact usSee pricingStart building
Node
​

    About Stytch

    Introduction
    Integration Approaches
      Full-stack overview
      Frontend (pre-built UI)
      Frontend (headless)
      Backend
    Migrations
      Migration overview
      Migrating users statically
      Migrating users dynamically
      Additional migration considerations
      Zero-downtime deployment
      Defining external IDs for users
      Exporting from Stytch
    Custom Domains
      Overview

    Authentication

    DFP Protected Auth
      Overview
      Setting up DFP Protected Auth
      Handling challenges
    Magic Links
    • Email Magic Links

      • Getting started with the API
        Getting started with the SDK
        Replacing your password reset flow
        Building an invite user flow
        Add magic links to an existing auth flow
        Adding PKCE to a Magic Link flow
        Magic Link redirect routing
    • Embeddable Magic Links

      • Getting started with the API
    MFA
      Overview
      Backend integration
      Frontend integration
    Mobile Biometrics
      Overview
    M2M Authentication
      Authenticate an M2M Client
      Rotate client secrets
      Import M2M Clients from Auth0
    OAuth
    • Identity providers

      • Overview
        Provider setup
      Getting started with the API (Google)
      Add Google One Tap via the SDK
      Email address behavior
      Adding PKCE to an OAuth flow
    Connected AppsBeta
      Setting up Connected Apps
      About Remote MCP Servers
    • Resources

      • Integrate with AI agents
        Integrate with MCP servers
        Integrate with CLI Apps
    Passcodes
      Getting started with the API
      Getting started with the SDK
    • Toll fraud

      • What is SMS toll fraud?
        How you can prevent toll fraud
      Unsupported countries
    Passkeys & WebAuthn
    • Passkeys

      • Passkeys overview
        Set up Passkeys with the frontend SDK
    • WebAuthn

      • Getting started with the API
        Getting started with the SDK
    Passwords
      Getting started with the API
      Getting started with the SDK
      Password strength policy
    • Email verification

      • Overview
        Email verification before password creation
        Email verification after password creation
    Sessions
      How to use sessions
      Backend integrations
      Frontend integrations
      Custom claims
      Custom claim templates
      Session tokens vs JWTs
      How to use Stytch JWTs
    TOTP
      Getting started with the API
      Getting started with the SDK
    Web3
      Getting started with the API
      Getting started with the SDK

    Authorization

    Implement RBAC with metadata

    3rd Party Integrations

    Planetscale
    Supabase
    Feathery
    Unit

    Testing

    E2E testing
    Sandbox values
Get support on SlackVisit our developer forum

Contact us

Consumer Authentication

/

Guides

/

Authentication

/

Passwords

/

Getting started with the API

Setting up passwords with the API

If you get stuck while working through this guide, feel free to ask questions in our forum, via support@stytch.com, or in our Slack community.

Step 1: Build a signup UX

First, you will want to design and build a signup experience in your application. In this flow, you will collect the user’s email address and have them set a password. You could consider collecting additional information, like name and phone number, during this step as well. Ultimately, you will only need to pass the email and password that you collected to Stytch’s Create user with password endpoint.

Password signup UIWeak password UI

A successful call will create a new user with the given credentials and start a session if a session_duration_minutes value is included.

You will also need to handle the following errors, and present suggestions in your UI:

  • duplicate_email: A user with this email already exists in your project. Inform the user to try a different email address, or alternatively prompt them to log in.
  • weak_password or breached_password: See the following step for more guidance.

Step 2: Add a password strength check to your signup UX

Passwords in Stytch must pass a strength test in order to be accepted. Password strength is determined by zxcvbn, which is a password strength estimator algorithm that scores on a scale of 0 to 4, and by confirming the provided password is not present in a list of leaked passwords maintained by HaveIBeenPwned. Attempting to set a password that is assigned a score of <= 2 will result in a weak_password error. Atetmpting to set a password that is present in the HaveIBeenPwned dataset will result in a breached_password error.

Password strength check

In your sign up flow, you can use Stytch’s Strength check endpoint to provide suggestions to your end users. This endpoint provides information about the potential password, the zxcvbn score, and helpful feedback for users on how to improve that score to an acceptable level.

Step 3: Build a login UX

Your login UX will usually be nearly identical to your signup UX, but you can skip the password validation which was included in the previous step.

Collect the user’s email and password, and pass it directly to Authenticate user with password. A successful call will authenticate the user, and start a session if a session_duration_minutes value is included.

Password signup UIWeak password UI

You should handle the following errors and present suggestions in your UI:

  • unauthorized_credentials and email_not_found: The user provided an email/password combination that is invalid. Ask the user to try again.

  • reset_password: The user’s password requires a reset before they can successfully authenticate. There are three scenarios which can trigger a password reset error: the password appearing in the HaveIBeenPwned dataset, a migrated password not passing the strength test, or (for security reasons) a scenario where the user most recently leveraged passwordless authentication for the first time to access the same account. The last scenario requires a password reset to prevent account pre-hijacking threats.

    Prompt the user to reset their password. The following step covers building this flow.

Step 4: Add a reset password flow

Passwords are commonly forgotten, so you will need to present a reset password affordance to your users if they are having trouble logging in. Additionally, if the user’s password appears in a breach, Stytch will require a password reset for the user.

A password reset flow has two parts. First, an email is sent to the user which includes a link back to your application; this link contains a unique token which is used for validation. Once the link is clicked, which ensures the user has control of the email address associated with the account, they are then able to set a new password.

Use Start email password reset to begin the flow. This endpoint requires an email address and additionally accepts a redirect URL if you plan to use non-default values (i.e. redirect URLs that are not set as default in your Dashboard). An email_not_found error will be returned if you attempt to reset the password for an account which does not exist.

A sample reset password email is shown below. The user will be presented with two options: "Reset password", and "Log in without password". To support the Reset password flow, build a page in your application where users will set a new password. Add the URL of this page as a Reset Password type to your redirect URLs in the Stytch dashboard. On this page, you will collect the new password from the user, along with the token available in the URL query parameters. These two values are passed to Password reset by email along with an optional session_duration_minutes to complete the reset.

Note that the provided password will need to pass the strength check, so you should provide a similar UX as your sign up flow.

Password reset sebd UIPassword reset email UIPassword reset UX

To support the Log in without password flow, you will need to support login via Email Magic Links within your application. Choose a URL for users that take this flow to be redirected to and add the URL as a Login type to your redirect URLs in the Stytch dashboard. On this route, you will collect the token provided in the URL query parameters. The token should be passed to Authenticate magic link along with an optional session_duration_minutes to complete user authentication. On a successful authentication you can now present the user with a logged in experience.

Note that going through the Email Magic Link flow will not resolve a reset_email error.

Step 5: You're Done!

You have now built all the components for a great password authentication experience powered by Stytch! Have any feedback after integrating? Get in touch with us and tell us what you think in our forum, via support@stytch.com, or in our community Slack.

Password flow

Step 1: Build a signup UX

Step 2: Add a password strength check to your signup UX

Step 3: Build a login UX

Step 4: Add a reset password flow

Step 5: You're Done!