# Login

Authenticate a user with their Fahipay ID card number and password.

---

## Endpoint

```
POST https://fahipay.mv/api/app/login/
```

---

## Request

**Content-Type:** `multipart/form-data`

### Form Fields

| Field | Value | Notes |
|---|---|---|
| `email` | `A123456` | The user's national ID card number (e.g. `A123456`) |
| `password` | `••••••••••••••` | The user's Fahipay password |
| `grant_type` | `auth_id` | Always `auth_id` |
| `lang` | `en` | Always `en` |
| `version` | `2.0.0` | App version string |
| `platform` | `BasedBank` | Client identifier (`app` in the original Fahipay app) |
| `device[available]` | `true` | See [common device fields](README.md#common-form-fields-device-info) |
| `device[platform]` | `Android` | |
| `device[uuid]` | `a1b2c3d4e5f60718` | Persistent 16-char hex UUID, generated once per install |
| `device[model]` | `22101320I` | `Build.MODEL` |
| `device[manufacturer]` | `Xiaomi` | `Build.MANUFACTURER` |
| `device[isVirtual]` | `false` | |
| `device[serial]` | `unknown` | |

> **Note:** The field name is `email` but the value is the ID card number, not an email address.

---

## curl Example

```bash
curl --request POST \
  --url https://fahipay.mv/api/app/login/ \
  --compressed \
  --header 'accept: application/json' \
  --header 'accept-encoding: gzip, deflate, br' \
  --header 'connection: keep-alive' \
  --header 'user-agent: Mozilla/5.0 (Linux; Android 14; 22101320I Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36' \
  --form 'email=A123456' \
  --form 'password=your_password' \
  --form 'grant_type=auth_id' \
  --form 'lang=en' \
  --form 'version=2.0.0' \
  --form 'platform=BasedBank' \
  --form 'device[available]=true' \
  --form 'device[platform]=Android' \
  --form 'device[uuid]=a1b2c3d4e5f60718' \
  --form 'device[model]=22101320I' \
  --form 'device[manufacturer]=Xiaomi' \
  --form 'device[isVirtual]=false' \
  --form 'device[serial]=unknown'
```

---

## Responses

### Success — 2FA required

The user has TOTP two-factor authentication enabled. Proceed to the [OTP step](02-otp.md).

```json
{
  "two_factor_required": true,
  "two_factor_method": "totp",
  "title": "Success",
  "msg": "You are now logged in.",
  "type": "success"
}
```

| Field | Type | Description |
|---|---|---|
| `two_factor_required` | `bool` | `true` — must call `/api/app/otp/` next |
| `two_factor_method` | `string` | `"totp"` — standard TOTP (RFC 6238) |
| `type` | `string` | `"success"` on success, `"error"` on failure |

The `__Secure-sess` session cookie is obtained from the session initialisation step (see [Session Cookie](#session-cookie) below), not from this response.

---

### Success — No 2FA

The user does not have 2FA enabled. The `authID` is returned directly — no OTP step needed.

```json
{
  "two_factor_required": false,
  "authID": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "title": "Success",
  "msg": "You are now logged in.",
  "type": "success"
}
```

| Field | Type | Description |
|---|---|---|
| `two_factor_required` | `bool` | `false` — login is complete |
| `authID` | `string` | 40-char hex token; use as `authid` header for all subsequent requests |

---

### Failure

```json
{
  "title": "Error",
  "msg": "Invalid credentials",
  "type": "error"
}
```

`type` is `"error"` and `msg` contains a human-readable reason.

---

## Session Cookie

Before calling `/api/app/login/`, the client must make an initialisation request to obtain the `__Secure-sess` cookie:

```
GET https://fahipay.mv/api/app/lang/data/
User-Agent: <webview UA>
```

The server sets the `__Secure-sess` cookie on this response. It must be sent with every subsequent request (login, OTP, and all authenticated calls). It is a standard HTTP cookie with the `Secure` flag:

```
Set-Cookie: __Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx; Path=/; Secure; HttpOnly; SameSite=Strict
```

Store both the cookie value and the `authID` together to represent a persisted session.

---

## Next Steps

- If `two_factor_required` is `true` → proceed to **[OTP / 2FA](02-otp.md)**
- If `two_factor_required` is `false` → skip to **[Profile](03-profile.md)**

---

&nbsp;

---

[← README](README.md) &nbsp;&nbsp;&nbsp; **Next →** [OTP / 2FA](02-otp.md)