> ## 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

<Steps>
  <Step title="Authenticate with password">
    Members log in by providing their email and password using the [Authenticate](/docs/api-reference/b2b/api/passwords/authenticate) 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"
      }
    }
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Password reset flows

Stytch provides two methods for resetting passwords:

<Tabs>
  <Tab title="Reset by Email" icon="mail">
    Send a password reset email to the member using the [Password Reset by Email Start](/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-email-start) 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](/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-email) 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>

  <Tab title="Reset by Existing Password" icon="key">
    Allow authenticated members to change their password using the [Password Reset by Existing Password](/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-existing-password) 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.
  </Tab>
</Tabs>

## Password strength validation

Check password strength before allowing members to set passwords using the [Strength Check](/docs/api-reference/b2b/api/passwords/strength-check) 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

<CardGroup cols={2}>
  <Card title="Password strength policy" icon="shield-check" href="/docs/multi-tenant-auth/authentication/passwords/strength-policy">
    Configure password requirements
  </Card>

  <Card title="MFA guide" icon="lock" href="/docs/multi-tenant-auth/authentication/mfa/overview">
    Add multi-factor authentication
  </Card>
</CardGroup>