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

# Login

> Authenticate users and obtain access tokens

# Login API

The login endpoints allow users to authenticate with the ProductFlo API and obtain access tokens for subsequent API calls.

## Email Login

<Card title="POST /auth/login" icon="sign-in" iconType="duotone">
  Authenticate a user with email and password
</Card>

Authenticates a user with their email and password, returning a session with access and refresh tokens.

### Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.productflo.io/auth/login \
      -H "Content-Type: application/json" \
      -d '{
        "email": "user@example.com",
        "password": "your-password"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.productflo.io/auth/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: 'user@example.com',
        password: 'your-password',
      }),
      credentials: 'include' // Important for cookie-based auth
    });

    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://api.productflo.io/auth/login',
        json={
            'email': 'user@example.com',
            'password': 'your-password'
        }
    )

    data = response.json()
    ```
  </Tab>
</Tabs>

### Request Body

<ParamField body="email" type="string" required>
  The user's email address
</ParamField>

<ParamField body="password" type="string" required>
  The user's password
</ParamField>

### Response

<ResponseField name="user" type="object">
  User information

  <Expandable title="User properties">
    <ResponseField name="id" type="string">
      The user's unique identifier
    </ResponseField>

    <ResponseField name="app_metadata" type="object">
      Metadata about the user's account
    </ResponseField>

    <ResponseField name="user_metadata" type="object">
      User-specific metadata including profile information
    </ResponseField>

    <ResponseField name="aud" type="string">
      The audience the token is intended for
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email address
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="session" type="object">
  Session information

  <Expandable title="Session properties">
    <ResponseField name="access_token" type="string">
      JWT token for API access
    </ResponseField>

    <ResponseField name="refresh_token" type="string">
      Token used to refresh the access token
    </ResponseField>

    <ResponseField name="expires_in" type="number">
      Number of seconds until the token expires
    </ResponseField>

    <ResponseField name="token_type" type="string">
      Type of token (usually "bearer")
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```json theme={null}
  {
    "email": "user@example.com",
    "password": "your-password"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "aud": "authenticated",
      "role": "authenticated",
      "email": "user@example.com",
      "email_confirmed_at": "2023-01-01T12:00:00.000Z",
      "phone": "",
      "confirmed_at": "2023-01-01T12:00:00.000Z",
      "last_sign_in_at": "2023-05-01T12:34:56.789Z",
      "app_metadata": {
        "provider": "email",
        "providers": ["email"]
      },
      "user_metadata": {
        "first_name": "John",
        "last_name": "Doe",
        "avatar_url": "https://example.com/avatar.jpg"
      },
      "identities": [],
      "created_at": "2023-01-01T12:00:00.000Z",
      "updated_at": "2023-05-01T12:34:56.789Z"
    },
    "session": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ..."
    }
  }
  ```
</ResponseExample>

## Phone Login

<Card title="POST /auth/phone-login" icon="phone" iconType="duotone">
  Authenticate a user with phone number and password
</Card>

Authenticates a user with their phone number and password, returning a session with access and refresh tokens.

### Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.productflo.io/auth/phone-login \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+12345678901",
        "password": "your-password"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.productflo.io/auth/phone-login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        phone_number: '+12345678901',
        password: 'your-password',
      }),
      credentials: 'include'
    });

    const data = await response.json();
    ```
  </Tab>
</Tabs>

### Request Body

<ParamField body="phone_number" type="string" required>
  The user's phone number in international format (e.g., +12345678901)
</ParamField>

<ParamField body="password" type="string" required>
  The user's password
</ParamField>

### Response

Same structure as the email login response.

## Magic Link Authentication

<Card title="POST /auth/magic-link" icon="link" iconType="duotone">
  Send a magic link to the user's email for passwordless login
</Card>

Sends a magic link to the user's email address for passwordless authentication.

### Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.productflo.io/auth/magic-link \
      -H "Content-Type: application/json" \
      -d '{
        "email": "user@example.com"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.productflo.io/auth/magic-link', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: 'user@example.com',
      })
    });

    const data = await response.json();
    ```
  </Tab>
</Tabs>

### Request Body

<ParamField body="email" type="string" required>
  The user's email address
</ParamField>

### Response

<ResponseField name="message" type="string">
  Confirmation message
</ResponseField>

<RequestExample>
  ```json theme={null}
  {
    "email": "user@example.com"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "message": "Magic link sent to email"
  }
  ```
</ResponseExample>

## OTP Authentication

<Card title="POST /auth/phone-otp" icon="mobile" iconType="duotone">
  Send a one-time password to the user's phone
</Card>

Sends a one-time password (OTP) to the user's phone number for authentication.

### Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.productflo.io/auth/phone-otp \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+12345678901"
      }'
    ```
  </Tab>
</Tabs>

### Request Body

<ParamField body="phone_number" type="string" required>
  The user's phone number in international format
</ParamField>

### Response

<ResponseField name="message" type="string">
  Confirmation message
</ResponseField>

<RequestExample>
  ```json theme={null}
  {
    "phone_number": "+12345678901"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "message": "OTP sent to phone number"
  }
  ```
</ResponseExample>

## Verify OTP

<Card title="POST /auth/verify-phone-otp" icon="check" iconType="duotone">
  Verify a one-time password sent to the user's phone
</Card>

Verifies the one-time password (OTP) sent to the user's phone number.

### Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.productflo.io/auth/verify-phone-otp \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+12345678901",
        "token": "123456"
      }'
    ```
  </Tab>
</Tabs>

### Request Body

<ParamField body="phone_number" type="string" required>
  The user's phone number in international format
</ParamField>

<ParamField body="token" type="string" required>
  The OTP code received by the user
</ParamField>

### Response

Same structure as the login response, containing user and session information.