Passwords

The JavaScript SDK provides headless methods to authenticate passwords, reset passwords, and check password strength. It also provides a pre-built UI component that supports password logins.

Methods

The SDK provides methods that can be used to authenticate password-based members, reset passwords, and add a password to an existing passwordless member.

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

Authenticate

The authenticate method wraps the Authenticate password API endpoint.

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the new factor to the existing Member Session.

If there is an intermediate session token, the SDK will call the endpoint with it. If the resulting set of factors satisfies the organization's primary authentication requirements and MFA requirements, the intermediate session token will be consumed and converted to a Member Session. If not, the same intermediate session token will be returned.

If this method succeeds and the Member is not required to complete MFA, the Member will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

If this method succeeds and MFA is required, the intermediate session token will be stored in the browser as a cookie.

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

Method parameters

email_address* string
password* string
session_duration_minutes* int
organization_id* string
import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

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

  const authenticatePassword = useCallback(() => {
    stytchClient.passwords.authenticate({
        email_address: 'sandbox@stytch.com',
        organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
        password: '9eAiIrU7wQ@6T$PU',
        session_duration_minutes: 60,
    });
  }, [stytchClient]);

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

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "method_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "reset_sessions": false,
    "session_jwt": "example_jwt",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "intermediate_session_token": "",
    "member_authenticated": true,
    "mfa_required": null,
    "member_session": {...},
    "member": {...},
    "organization": {...}
}

Reset by email start

Method parameters

email_address* string
organization_id* string
reset_password_redirect_url string
login_redirect_url string
reset_password_expiration_minutes string
reset_password_template_id string
import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const ResetPasswordStart = () => {
  const stytchClient = useStytchB2BClient();

  const resetPasswordStart = useCallback(() => {
    stytchClient.passwords.resetPasswordStart({
        email_address: 'sandbox@stytch.com',
        organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
    });
  }, [stytchClient]);

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

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member_email_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
    "member": {...}
}

Reset by email

The resetByEmail method wraps the Reset by Email Password API endpoint.

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the new factor to the existing Member Session.

If there is an intermediate session token, the SDK will call the endpoint with it. If the resulting set of factors satisfies the organization's primary authentication requirements and MFA requirements, the intermediate session token will be consumed and converted to a Member Session. If not, the same intermediate session token will be returned.

If this method succeeds and the Member is not required to complete MFA, the Member will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

If this method succeeds and MFA is required, the intermediate session token will be stored in the browser as a cookie.

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

Method parameters

password_reset_token* string
password* string
session_duration_minutes* int
import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const ResetPassword = () => {
  const stytchClient = useStytchB2BClient();

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

  const resetPassword = useCallback(() => {
    stytchClient.passwords.resetByEmail({
      token: token,
      password: '9eAiIrU7wQ@6T$PU',
      session_duration_minutes: 60,
    });
  }, [stytchClient, token]);

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

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "member_id": "",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "intermediate_session_token": "",
    "member_authenticated": true,
    "mfa_required": null,
    "member_email_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member": {...}
}

Reset by existing password

The resetByExistingPassword method wraps the Reset by existing password Password API endpoint.

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the new factor to the existing Member Session.

If this method succeeds and the Member is not required to complete MFA, the Member will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

If this method succeeds and MFA is required, the intermediate session token will be stored in the browser as a cookie.

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

Method parameters

session_duration_minutes* int
email_address* string
new_password* string
existing_password* string
organization_id* string
import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const ResetPassword = () => {
  const stytchClient = useStytchB2BClient();

  const resetPassword = useCallback(() => {
    stytchClient.passwords.resetByExistingPassword({
        email_address: 'sandbox@stytch.com',
        existing_password: 'existing_password',
        new_password: '9eAiIrU7wQ@6T$PU',
        session_duration_minutes: 60,
        organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
    });
  }, [stytchClient]);

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

RESPONSE

200
{
    "intermediate_session_token": "",
    "member": {...},
    "member_authenticated": true,
    "mfa_required": null,
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member_session": {...},
    "organization": {...}
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "session_jwt": "example_jwt",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "status_code": 200
}

Reset by session

The resetBySession method wraps the Reset by Session Password API endpoint. The Member must have an active Member Session for this method to be called.

If this method succeeds, the password factor will be added to the existing Member 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 useStytchMemberSession hook if you are using React.

Method parameters

password* string
organization_id* string
import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const ResetPassword = () => {
  const stytchClient = useStytchB2BClient();

  const resetPassword = useCallback(() => {
    stytchClient.passwords.resetBySession({
        organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
        password: '9eAiIrU7wQ@6T$PU',
    });
  }, [stytchClient]);

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

RESPONSE

200
{
    "intermediate_session_token": "",
    "member": {...},
    "member_authenticated": true,
    "mfa_required": null,
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member_session": {...},
    "organization": {...}
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "session_jwt": "example_jwt",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "status_code": 200
}

Strength check

This method allows you to check whether or not the Member’s provided password is valid, and to provide feedback to the Member 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_address string
import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const StrengthCheck = () => {
    const stytchClient = useStytchB2BClient();

  const strengthCheck = useCallback(() => {
    stytchClient.passwords.strengthCheck({
      password: '9eAiIrU7wQ@6T$PU',
    });
  }, [stytchClient]);

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

RESPONSE

200 - LUDS invalid
{
    "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

Our pre-built B2B login UI component supports password authentication when the authFlowType is set to Organization, allowing Members to log into a specific Organization using their email address and password. Our Passwords product is not compatible with the Discovery flow.

The Passwords functionality in our pre-built login component works on top of our Authenticate password method.

To add Passwords to the login component, add passwords to the products array in your config object, and add a passwordOptions object to your config as well. You'll also need to make sure Passwords is enabled in the Frontend SDKs tab in the Stytch Dashboard.

Screenshot of B2B Passwords pre-built UI

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

import { StytchB2B } from '@stytch/react/b2b';
import React from 'react';

const PasswordLogin = () => {
  const config = {
    authFlowType: "Organization",
    products: ['passwords'],
    passwordOptions: {
        loginRedirectURL: "https://example.com/authenticate",
        resetPasswordRedirectURL: "https://example.com/resetPassword",
        resetPasswordExpirationMinutes: 20
      },
    sessionOptions: {
      sessionDurationMinutes: 60,
    },
  };

  const style = {
    fontFamily: 'Arial',
  };

  const callbacks = {
    onEvent: ({ type, data }) => {
      console.log(type, data);
    },
    onError: (data) => {
      console.log(data);
    },
  };

  return <StytchB2B callbacks={callbacks} config={config} styles={style} />;
};

export default PasswordLogin;