JavaScript SDK - Passwords | Stytch Consumer authentication

Passwords

Stytch supports creating, storing, and authenticating password based users, as well as support for account recovery (password reset) and account deduplication with passwordless login methods.

Methods

The SDK provides methods that can be used to create and authenticate password based users.

To call these methods, Passwords must be enabled in the SDK Configuration page of the Stytch dashboard.

Create

The send method wraps the create Password API endpoint.

Method parameters

email* string

password* string

session_duration_minutes* int

import { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const createPassword = useCallback(() => {
    stytchClient.passwords.create({
      email: '${exampleEmail}',
      password: 'hWFpdbni!Ej5mosW',
      session_duration_minutes: 60,
    });
  }, [stytchClient]);

  return <button onClick={createPassword}>Create Password</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
  }

Authenticate

The authenticate method wraps the authenticate Password API endpoint.

If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.

Method parameters

email* string

password* string

session_duration_minutes* int

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const authenticatePassword = useCallback(() => {
    stytchClient.passwords.authenticate({
      email: '${exampleEmail}',
      password: 'hWFpdbni!Ej5mosW',
      session_duration_minutes: 60,
    });
  }, [stytchClient]);

  return <button onClick={authenticatePassword}>Authenticate Password</button>;
};

RESPONSE

{
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "session": null,
    "session_jwt": "",
    "session_token": "",
    "status_code": 200,
    "user": {...},
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
  }

Reset by email start

The resetByEmailStart method wraps the reset_by_email_start Password API endpoint.

Method parameters

email* string

Configuration object

Additional configuration.

reset_password_redirect_url string

login_redirect_url string

reset_password_expiration_minutes int

reset_password_template_id string

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const resetPasswordStart = useCallback(() => {
    stytchClient.passwords.resetByEmailStart({
      email: '${exampleEmail}',
    });
  }, [stytchClient]);

  return <button onClick={resetPasswordStart}>Reset Password Start</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953"
  }

Reset by email

The resetByEmail method wraps the reset_by_email Password API endpoint.

If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.

Method parameters

token* string

password* string

session_duration_minutes* int

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const token = new URLSearchParams(window.location.search).get('token');

  const resetPassword = useCallback(() => {
    stytchClient.passwords.resetByEmail({
      token: token,
      password: 'hWFpdbni!Ej5mosW',
      session_duration_minutes: 60,
    });
  }, [stytchClient, token]);

  return <button onClick={resetPassword}>Reset Password</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
  }

Reset by existing password

The resetByExistingPassword method wraps the reset_by_existing_password Password API endpoint.

If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.

Method parameters

session_duration_minutes* int

email* string

new_password* string

existing_password* string

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const resetPassword = useCallback(() => {
    stytch.passwords.resetByExistingPassword({
      existing_password: 'existing_password',
      new_password: 'hWFpdbni!Ej5mosW',
      session_duration_minutes: 60,
      email: 'sandbox@stytch.com',
    });
  }, [stytchClient]);

  return <button onClick={resetPassword}>Reset Password</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
  }

Reset by session

The resetBySession method wraps the reset_by_session Password API endpoint.

If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.

Method parameters

password* string

session_duration_minutes* int

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const resetPassword = useCallback(() => {
    stytchClient.passwords.resetBySession({
      password: 'hWFpdbni!Ej5mosW',
      session_duration_minutes: 60,
    });
  }, [stytchClient]);

  return <button onClick={resetPassword}>Reset Password</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "session": null
  }

Strength check

This method allows you to check whether or not the user’s provided password is valid, and to provide feedback to the user on how to increase the strength of their password. All passwords must pass the strength requirements to be accepted as valid.

The strengthCheck method wraps the strength_check Password API endpoint.

Method parameters

password* string

email string

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const createPassword = useCallback(() => {
    stytchClient.passwords.strengthCheck({
      email: '${exampleEmail}',
      password: 'hWFpdbni!Ej5mosW',
    });
  }, [stytchClient]);

  return <button onClick={strengthCheck}>Strength Check</button>;
};

RESPONSE

{
    "breach_detection_on_create": true,
    "breached_password": false,
    "feedback": {
      "suggestions": null,
      "warning": null,
      "luds_requirements": {
        "has_digit": true,
        "has_lower_case": false,
        "has_symbol": false,
        "has_upper_case": false,
        "missing_characters": 6,
        "missing_complexity": 1
      }
    },
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "score": 0,
    "status_code": 200,
    "strength_policy": "luds",
    "valid_password": false
  }

UI components

The SDK also comes with a pre-built UI component for our Passwords product.

To add passwords to the login UI, add Products.passwords to the products array in the configuration and the appropriate passwordOptions.

To see all authentication and customization options, see the UI config section below.

import React from 'react';
import { Products } from '@stytch/vanilla-js';
import { StytchLogin } from '@stytch/react';

const config = {
  passwordOptions: {
    loginExpirationMinutes: 30,
    loginRedirectURL: 'https://example.com/authenticate',
    resetPasswordExpirationMinutes: 30,
    resetPasswordRedirectURL: 'https://example.com/authenticate',
  },
  products: [Products.passwords],
};

export const Login = () => {
  return <StytchLogin config={config} />;
};

There is a separate component for the password reset flow.

The component takes in a passwordResetToken as a prop along with all props the StytchLogin component supports.

To see all authentication and customization options, see the UI config section below.

import React from 'react';
import { Products } from '@stytch/vanilla-js';
import { StytchPasswordReset } from '@stytch/react';

const config = {
  passwordOptions: {
    loginExpirationMinutes: 30,
    loginRedirectURL: 'https://example.com/authenticate',
    resetPasswordExpirationMinutes: 30,
    resetPasswordRedirectURL: 'https://example.com/authenticate',
  },
  products: [Products.passwords],
};

export const ResetPassword = () => {
  const passwordResetToken = new URLSearchParams(window.location.search).get('token');
  return <StytchPasswordReset config={config} passwordResetToken={passwordResetToken} />;
};