Passwords overview

Passwords allow members to authenticate using a traditional email and password combination. Stytch handles password hashing, strength validation, and secure storage while providing flexible reset flows.

Password authentication flow

Authenticate with password

Members log in by providing their email and password using the Authenticate endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/passwords/authenticate \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "email_address": "user@example.com",
    "password": "correct-horse-battery-staple",
    "session_duration_minutes": 60
  }'

Key parameters:

organization_id: The organization the member belongs to (required)
email_address: Member’s email address (required)
password: Member’s password (required)
session_duration_minutes: How long the session should last (default: 60)

Response:

{
  "status_code": 200,
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "session_jwt": "eyJhbGc...",
  "member_authenticated": true,
  "member": {
    "email_address": "user@example.com",
    "status": "active"
  }
}

Handle MFA (if required)

If the organization requires MFA, the response will have member_authenticated: false and include an intermediate_session_token:

{
  "member_authenticated": false,
  "intermediate_session_token": "intermediate_session_token_...",
  "member_id": "member-test-...",
  "organization_id": "organization-test-..."
}

Use the intermediate session token to complete an MFA challenge (TOTP or SMS) before the member is fully authenticated.

Password reset flows

Stytch provides two methods for resetting passwords:

Reset by Email
Reset by Existing Password

Send a password reset email to the member using the Password Reset by Email Start endpoint:Start the reset:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/passwords/email/reset/start \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "email_address": "user@example.com"
  }'

The member receives an email with a reset link. When they click it, extract the password_reset_token from the callback URL.Complete the reset with the Password Reset by Email endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/passwords/email/reset \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "password_reset_token": "token-from-email-...",
    "password": "new-password-123",
    "session_duration_minutes": 60
  }'

Returns a session for the member with their new password set.

Allow authenticated members to change their password using the Password Reset by Existing Password endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/passwords/existing_password/reset \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "email_address": "user@example.com",
    "existing_password": "old-password",
    "new_password": "new-password-123",
    "session_duration_minutes": 60
  }'

The member must provide their current password to set a new one. This is useful for account settings or password change flows.

Password strength validation

Check password strength before allowing members to set passwords using the Strength Check endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/passwords/strength_check \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "email_address": "user@example.com",
    "password": "password123"
  }'

Response:

{
  "status_code": 200,
  "valid_password": false,
  "score": 2,
  "breached_password": true,
  "feedback": {
    "warning": "This password is commonly used",
    "suggestions": [
      "Add more words or characters",
      "Avoid common patterns"
    ]
  }
}

The endpoint validates passwords against your configured strength policy (LUDS or zxcvbn) and checks if they’ve appeared in known breaches.

Password authentication flow

Password reset flows

Password strength validation

Learn more

Password strength policy

MFA guide

​Password authentication flow

​Password reset flows

​Password strength validation

​Learn more

Password strength policy

MFA guide

Password authentication flow

Password reset flows

Password strength validation

Learn more