Passwords overview

Passwords and their encryption technologies, like hashing passwords and salting passwords, have been around for decades. We've built on top of that, giving the password some modern upgrades to not just improve security and the end user experience, but to also act as the bridge to passwordless.

API referenceSDK reference

Guides

Step-by-step guides to quickly get up and running with Stytch Passwords.

Getting started 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.

  1. 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.

    Step description
    Step description

    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: See the following step for more guidance.

  2. 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 or is present in the HaveIBeenPwned dataset will result in a weak_password error.

    Step description

    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.

  3. 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.

    Step description
    Step description

    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.

  4. 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.

    Step description
    Step description
    Step description

    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.

  5. 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, support@stytch.com, or in our Slack community.

    Step description

Getting started with Passwords using an SDK

Use the selector below to select the SDK you are using.

Choose an SDK

React

Step 1: Configure your project in the Stytch dashboard

Before adding passwords to your application you will need to make the following project configurations within the Stytch dashboard:

  1. Create a Login and Reset Password redirect URL on the redirect URL configuration page. These will used during the password reset flow.
  2. Within SDK Configuration, authorize the domain(s) (eg. http://localhost:3000) the SDK will run on. Under Auth methods enable the Passwords toggle, and the Email magic links > Enable the LoginOrCreate Flow toggle.
  3. Finally, under API keys, save your project's public_token for later.

Step 2: Add Stytch to your project

2.1 Add packages

2.2 Initialize Stytch

At the top level of your application you will need to initialize the Stytch client using the public_token saved in the previous step.

Step 3: Configure sign up and login

Next, create a component that will render on your sign up, and login page. Within this component you will configure, and render the Stytch UI. The Stytch UI accepts a config object as an argument; learn more about this object here. You will need the Login and Password Reset redirect URLs you configured in step one.

Step 4: Configure password reset

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.

Triggering a password reset is handled by the Stytch UI which was configured in the previous step. Now, we will build a separate component which handles the second step of the password reset. Create a component which will appear on the page that your Password Reset redirect url points to. On this page we will configure and render the password reset Stytch UI.

Configure magic links

The password reset email sent by Stytch includes an additional button which allows the user to login directly. Our data indicates a large portion of password resets are initiated with the intention to login; by providing a Login without a password option during the reset flow you can increase your number of active users, and their engagement with your application.

Image

The "Login without a password" button is powered by a Magic link. On the page your Login redirect URL points to you will need to capture the token value from the URL query parameters, and authenticate it.

Step 5: Tie it all together

You have now built all the pieces needed for a password sign up and log in flow that handles both password resets, and magic link passwordless login. When a user logs in successfully the SDK will automatically start and manage a session on your behalf. You can learn more about how to use sessions here.

Have any feedback after integrating? Get in touch with us and tell us what you think in our forum, support@stytch.com, or in our Slack community.

Password strength policy

Stytch offers two different password strength strategies for you to choose from, zxcvbn and Lowercase Uppercase Digits Special Characters (LUDS). On top of these two strategies, we also offer breach detection, powered by HaveIBeenPwned to protect your users from password breaches.

You may choose any mix of these strategies for your Stytch Project. For example, you may choose to use LUDS for password complexity plus breach detection, or zxcvbn without breach detection.

By default, our Passwords product uses zxcvbn for password strength and automatically protects your users against password breaches. If that doesn't fit your needs, you may configure your desired strategy by contacting support@stytch.com.

zxcvbn

zxcvbn is a password strength estimation library developed originally by Dropbox. It is a complex password strength strategy that checks for the presence of dictionary words, common passwords, and common patterns. It does not explicitly check for lowercase letters, uppercase letters, digits, or special characters.

Some end users find zxcvbn to be too strict, and may be unable to create a password that meets the requirements. If you find that your users are unable to create a password that meets the requirements, you may want to consider using LUDS instead.

You can find examples of zxcvbn passwords and an interactive tool to test passwords at this hosted zxcvbn checker.

Example

If a user provides a commonly used password like, "p@ssword1", the response from our Strength check endpoint will look like the following:

{
  "breach_detection_on_create": true,
  "breached_password": false,
  "feedback": {
    "luds_requirements": null,
    "suggestions": [
      "Add another word or two. Uncommon words are better.",
      "Predictable substitutions like '@' instead of 'a' don't help very much."
    ],
    "warning": "This is a top-100 common password."
  },
  "request_id": "request-id-test-86779128-d4e7-4dd4-a588-88faa570f638",
  "score": 0,
  "status_code": 200,
  "strength_policy": "zxcvbn",
  "valid_password": false
}

You may use the warning and suggestions fields to provide feedback directly to your users to help them craft a stronger password that will pass your requirements.

LUDS

LUDS stands for Lowercase Uppercase Digits Special Characters. It is a simple password strength strategy that checks for the presence of lowercase letters, uppercase letters, digits, and special characters. It does not check for dictionary words or common passwords.

Example

For this example, we will use the following password strength policy:

  • Strength policy: LUDS
  • LUDS minimum length: 8
  • LUDS complexity: 4

If a user provides a password of, "Lorem1!", the password will be considered invalid. The password contains the necessary complexity, symbols, numbers, and upper and lower case letters, but is not of sufficient length. The response from our Strength check endpoint would look like the following:

{
	"breach_detection_on_create": true,
	"breached_password": false,
	"feedback": {
        "luds_requirements": {
            "has_digit": true,
            "has_lower_case": true,
            "has_symbol": true,
            "has_upper_case": true,
            "missing_characters": 2,
            "missing_complexity": 0
        },
		"suggestions": null,
		"warning": null
	},
	"request_id": "request-id-test-86779128-d4e7-4dd4-a588-88faa570f638",
	"score": 0,
	"status_code": 200,
	"strength_policy": "luds",
	"valid_password": false
}

You may use the missing_characters and missing_complexity fields to provide feedback to your users to help them craft a stronger password that will pass your requirements.

Breach detection

Stytch's Passwords product automatically protects your users against password breaches. We do this by checking the password against a list of known passwords that have been leaked in data breaches from HaveIBeenPwned. If the password is found in this list, we will reject the password and ask the user to choose a different one or reset their password if they have already used it previously.

Protecting your users against password breaches is a critical part of your security strategy. Password breaches are a common attack vector for hackers, and can be used to gain access to your users' accounts and compromise your app.

How to set a password strength policy

You may set a password strength policy for your Stytch Project by contacting support@stytch.com with your desired strength policy.

Password strength policy options

  • Check breach on creation: Determines whether to check for password breaches when a user creates a password.
  • Check breach on authentication: Determines whether to check for password breaches when a user authenticates with a password.
  • Strength policy: The password validation policy to use. Allowable values are zxcvbn and luds.
  • LUDS minimum length: The minimum number of characters required for a password. We recommend at minimum of at least 8 characters.
  • LUDS complexity: The minimum number of complexity requirements required for a password. Allowable numbers are 1-4. This value determines how many LUDS checks must be passed, e.g. 2 means that a password with a symbol and a number is valid because two of the four LUDS requirements are meant. You cannot choose which LUDS requirements are required, only how many.
  • Check password strength on authentication: During user migrations from another service with a password policy that is in compatible with Stytch's password strength policy options, you may temporarily disable password strength checks when a user authenticates. All new users will still be required to meet Stytch's password strength policy requirements.