Shihaam Abdul Rahman
ffe50467e7
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 3s
160 lines
4.2 KiB
Markdown
160 lines
4.2 KiB
Markdown
# 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)**
|
|
|
|
---
|
|
|
|
|
|
|
|
---
|
|
|
|
[← README](README.md) **Next →** [OTP / 2FA](02-otp.md)
|