# Start patient login

Canonical page: https://docs.ovok.com/api/tenant-authentication/start-patient-login

`POST /auth/tenant/Patient/login/start`

Starts a patient login for one tenant: checks the email and password and returns either a session code to exchange for tokens or, when the user has MFA enrolled, a login ID for the MFA step.

**Auth:** none. The tenant is named by `tenantCode`.
**Scope:** the project that owns `tenantCode`.

## Behaviour

- This is step 1 of a PKCE login. Generate a random `codeVerifier`, send its S256 hash as `codeChallenge` here, and send the `codeVerifier` itself to `POST /auth/tenant/Patient/login/token`.
- The account must be a Patient of the tenant's project. A Practitioner with the same email cannot log in here.
- `PATIENT_LOGIN_ENABLED` on the project must not be `false` (it defaults to on).
- Response `nextStep`:
  - `token`: no MFA. Pass `sessionCode` to `login/token`.
  - `mfa`: the user has MFA enrolled. Pass `loginId` and the current TOTP code to `POST /auth/tenant/Patient/login/mfa`.
- A wrong email, an unknown account, an account without a password and a wrong password all give the same 401 `Invalid email or password.`
- After 5 failed sign-ins for one email within 15 minutes, that email's sign-ins answer 429 with `Retry-After` for 15 minutes, the right password included, whether or not the email has an account. A successful sign-in resets the count.
- Error responses are delayed to take at least one second.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/Patient/login/start' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "max.mustermann@example.com",
    "password": "your-password",
    "tenantCode": "my-medical-project",
    "codeChallenge": "<base64url S256 hash of your codeVerifier>"
  }'
```