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

# User Login

> Authenticate with email and password to obtain a JWT token for API access

## Overview

The login endpoint authenticates a healthcare professional and returns a JWT token used to access protected endpoints. It is the primary authentication method for the MediSync platform.

<Note>
  No authentication is required to call this endpoint. Platform messages are returned in **German**.
</Note>

## Body Parameters

<ParamField body="email" type="string" required>
  Registered email address. Validated as an email and normalized server-side.
</ParamField>

<ParamField body="password" type="string" required>
  Account password. Minimum 6 characters.
</ParamField>

<ParamField body="remember" type="boolean" default="false">
  If `true`, issues a 7-day token; otherwise the token is valid for 24 hours.
</ParamField>

<ParamField body="twoFactorCode" type="string">
  TOTP code (or a one-time backup code) for accounts with 2FA enabled. Omit it on the first call to receive the `202` 2FA challenge, then resubmit with the code.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when authentication succeeds.
</ResponseField>

<ResponseField name="token" type="string">
  JWT token for authenticating subsequent requests.
</ResponseField>

<ResponseField name="uid" type="string">
  The authenticated user's id.
</ResponseField>

<ResponseField name="userTitle" type="string">
  Medical title (Dr., Prof., …).
</ResponseField>

<ResponseField name="firstName" type="string">
  User's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  User's last name.
</ResponseField>

<ResponseField name="twoFactorEnabled" type="boolean">
  Whether the account has 2FA enabled.
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.medisync.me/api/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "doctor@example.com",
      "password": "your_password",
      "remember": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.medisync.me/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'doctor@example.com',
      password: 'your_password',
      remember: false
    })
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post('https://app.medisync.me/api/login', json={
      'email': 'doctor@example.com',
      'password': 'your_password',
      'remember': False
  })
  data = response.json()
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "uid": "6578a1b2c3d4e5f601234567",
    "userTitle": "Dr.",
    "firstName": "John",
    "lastName": "Doe",
    "twoFactorEnabled": false
  }
  ```
</ResponseExample>

## Two-Factor Authentication

If the account has 2FA enabled and `twoFactorCode` is omitted, the endpoint returns `202 Accepted` with a challenge instead of a token. Resubmit the same request including a valid `twoFactorCode`.

<ResponseExample>
  ```json 202 Accepted — 2FA required theme={null}
  {
    "success": true,
    "requires2FA": true,
    "message": "Bitte geben Sie Ihren 2FA-Code ein."
  }
  ```
</ResponseExample>

## Error Responses

<CodeGroup>
  ```json 400 Validation failed theme={null}
  {
    "error": "Bitte überprüfen Sie Ihre Eingaben."
  }
  ```

  ```json 401 Invalid email or password theme={null}
  {
    "failed": "Unauthorized Access",
    "error": "Ungültige E-Mail oder Passwort."
  }
  ```

  ```json 401 Email not verified theme={null}
  {
    "failed": "Email Not Verified",
    "error": "Bitte bestätigen Sie Ihre E-Mail-Adresse, bevor Sie sich anmelden.",
    "needsVerification": true
  }
  ```

  ```json 401 Invalid 2FA code theme={null}
  {
    "failed": "Invalid 2FA Code",
    "error": "Ungültiger 2FA-Code. Bitte versuchen Sie es erneut.",
    "requires2FA": true
  }
  ```

  ```json 429 Too many attempts theme={null}
  {
    "error": "Zu viele Anmeldeversuche. Bitte versuchen Sie es in 15 Minuten erneut.",
    "rateLimited": true
  }
  ```
</CodeGroup>

<Note>
  Authentication failures use a `failed` label alongside `error`, while validation and rate-limit errors return only `error`. The API does not return invented English `code` values — branch on the HTTP status and the fields shown above.
</Note>

## Rate Limiting

Login is limited to **10 attempts per 15 minutes per email address**. Exceeding the limit returns `429` with `rateLimited: true`; standard `RateLimit-*` headers (and `Retry-After`) are included.

## Next Steps

<CardGroup cols={2}>
  <Card title="Register" icon="user-plus" href="/api-reference/auth/register">
    Create a new healthcare-professional account.
  </Card>

  <Card title="User Profile" icon="user" href="/api-reference/users/get-profile">
    Retrieve the authenticated user's profile.
  </Card>
</CardGroup>