> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Passwords overview

> Authenticate members with passwords using the Stytch API

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

**1. Authenticate with password**

Members log in by providing their email and password using the [Authenticate](https://stytch.com/docs/api-reference/b2b/api/passwords/authenticate.md) endpoint:

```bash theme={null}
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:**

```json theme={null}
{
  "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"
  }
}
```

**2. Handle MFA (if required)**

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

```json theme={null}
{
  "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:

> [tab] Reset by Email
>
> Send a password reset email to the member using the [Password Reset by Email Start](https://stytch.com/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-email-start.md) endpoint:
>
> **Start the reset:**
>
> ```bash theme={null}
> 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](https://stytch.com/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-email.md) endpoint:**
>
> ```bash theme={null}
> 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.

> [tab] Reset by Existing Password
>
> Allow authenticated members to change their password using the [Password Reset by Existing Password](https://stytch.com/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-existing-password.md) endpoint:
>
> ```bash theme={null}
> 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](https://stytch.com/docs/api-reference/b2b/api/passwords/strength-check.md) endpoint:

```bash theme={null}
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:**

```json theme={null}
{
  "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.

## Learn more

> [card] [Password strength policy](https://stytch.com/docs/multi-tenant-auth/authentication/passwords/strength-policy.md)
>
> Configure password requirements

> [card] [MFA guide](https://stytch.com/docs/multi-tenant-auth/authentication/mfa/overview.md)
>
> Add multi-factor authentication
