> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Flutter — Identity API (verified routes and request rules)

Source: `modules/Identity/Routes/api.php`; `LoginRequest.php`, `RegisterRequest.php` on `main`. All paths below use the actual `/api/v1` prefix. All endpoints use `LocalizeIdentityErrors` middleware. Public authentication writes are rate limited with `throttle:auth`.


## Route inventory and response contracts (controller-verified)

All routes use `LocalizeIdentityErrors`. Public authentication writes and phone/deletion writes use `throttle:auth`; authenticated endpoints require `auth:sanctum`. Policy values (OTP length, password requirements) must be fetched rather than hardcoded. JSON examples below show shapes, not captured server responses.

| Method | Path (under `/api/v1`) | Auth | Success `data` / status | Request fields |
|---|---|---|---|---|
| GET | `/auth/password-policy` | Public | Password policy object / 200 | None |
| GET | `/auth/otp-policy` | Public | OTP policy object / 200 | None |
| POST | `/auth/register` | Public | Phone: `{status:"pending", ...CodeSentView}` / 201; email: `{token,user}` / 201 | Registration fields below |
| POST | `/auth/register/verify` | Public | `{token,user}` / 200 | `phone,code,password,device_name?` |
| POST | `/auth/register/resend` | Public | `{message,verification}` / 200 | `phone` |
| POST | `/auth/login` | Public | `{token,user}` / 200 | `phone?`, `email?`, `password`, `device_name?` |
| POST | `/auth/password/forgot` | Public | `{message}` / 200 | `email` |
| POST | `/auth/password/reset` | Public | `{message}` / 200 | `token,email,password,password_confirmation` |
| POST | `/auth/password/phone/request` | Public | `{message,verification}` / 200 | `phone` |
| POST | `/auth/password/phone/verify` | Public | `{reset_token}` / 200 | `phone,code,device_name?` |
| POST | `/auth/password/phone/reset` | Public | `{message}` / 200 | `reset_token,password,password_confirmation` |
| POST | `/auth/logout` | Bearer | Empty body / **204** | None |
| POST | `/auth/logout-all` | Bearer | Empty body / **204** | None |
| GET | `/me` | Bearer | `UserResource` / 200 | None |
| PATCH | `/me` | Bearer | Updated `UserResource` / 200 | `name?`, `email?`, `locale?` |
| POST | `/me/phone` | Bearer | `CodeSentView` / 200 | `phone` (new number) |
| POST | `/me/phone/verify` | Bearer | Updated `UserResource` / 200 | `phone,code` |
| POST | `/me/deletion` | Bearer | `{deleted:true,message}` / 200 | `password,reason?` |

### Authentication and registration request fields

| Field | Type | Requirement and validation | Applies to |
|---|---|---|---|
| `phone` | string | Phone-first registration/login conditional; max 30 characters; phone format checked in domain | Register/login; required in phone OTP flows |
| `email` | string | Email-first registration/login conditional; email format; registration max 190, uniqueness under applicable policy | Register/login; required for email reset |
| `name` | string | Required at registration, bounded by `User::MIN_NAME/MAX_NAME`; profile update `sometimes|required` | Register / PATCH me |
| `password` | string | Required; registration/reset must pass active `PasswordRule`, confirmation required; login/OTP verify require password string | Auth writes |
| `password_confirmation` | string | Must equal `password` when using `confirmed` rule | Registration and password reset |
| `accept_terms` | accepted boolean-like | Required accepted value | Register |
| `terms_version` | string or null | Optional, bounded by domain terms version maximum | Register |
| `city_id` | integer or null | Optional, min 1 | Register |
| `locale` | string | Optional, must be an enabled locale | Register / PATCH me |
| `device_name` | string | Optional, max 100; defaults to `api` in auth handler | Login, register/verify, email register, phone reset verify |
| `code` | digit string | Required; exact length is the configured `OneTimeCodes::codeLength()` | OTP verify endpoints |
| `reset_token` | string | Required, max 2000 | Phone password reset |
| `token` | string | Required | Email password reset |
| `reason` | string or null | Optional, max `User::MAX_DELETION_REASON` | Account deletion |

**Phone registration is two-step:** `POST /auth/register` responds 201 with `data.status=pending` and a sent-code view; only `/auth/register/verify` issues `{token,user}`. Email registration issues credentials immediately. A phone-registration OTP verification requires the **same password** as the first step.

**Login response example (shape only):**
```json
{"data":{"token":"<sanctum-token>","user":{"id":123}}}
```
The full `user` object is serialized by `UserResource`, not limited to `id`; clients must consume its actual fields. Store tokens securely and attach `Authorization: Bearer <token>` on protected calls. `logout` revokes the current token; `logout-all` revokes every token.

### OTP and password reset flows

| Step | Endpoint | Required JSON | Response contract |
|---|---|---|---|
| Request phone registration code | `POST /auth/register` | Full registration payload | `data.status=pending`, code-send metadata |
| Verify phone registration | `POST /auth/register/verify` | `{"phone":"...","code":"...","password":"..."}` | `data.token`, `data.user` |
| Resend registration code | `POST /auth/register/resend` | `{"phone":"..."}` | `data.message`, `data.verification` |
| Request phone reset | `POST /auth/password/phone/request` | `{"phone":"..."}` | `data.message`, `data.verification` |
| Verify phone reset | `POST /auth/password/phone/verify` | `{"phone":"...","code":"..."}` | `data.reset_token` |
| Set phone reset password | `POST /auth/password/phone/reset` | `{"reset_token":"...","password":"...","password_confirmation":"..."}` | `data.message` |
| Email reset link | `POST /auth/password/forgot` | `{"email":"..."}` | `data.message`; same answer whether account exists |
| Reset with email token | `POST /auth/password/reset` | `{"email":"...","token":"...","password":"...","password_confirmation":"..."}` | `data.message` |
| Request phone change | `POST /me/phone` | `{"phone":"..."}` | `data` is code-send metadata |
| Confirm phone change | `POST /me/phone/verify` | `{"phone":"...","code":"..."}` | `data` is refreshed `UserResource` |

Do not treat a code-sent response as proof the SMS was delivered. Handle cooldown responses and wrong/expired codes; OTP length and expiry come from `/auth/otp-policy`. Phone reset verify returns a **reset ticket**, not a login token.

### Profile update and deletion

`PATCH /me` accepts optional `name` (`min:User::MIN_NAME`, `max:User::MAX_NAME`), `email` (RFC email, max 190, unique among non-pending users except self), and `locale` (enabled language). It returns the refreshed `UserResource`; phone changes require the separate two-step OTP flow. `POST /me/deletion` accepts required `password` (string, max 255) and optional `reason` (string, domain max), re-checks deletion conditions on the server, and returns `{"data":{"deleted":true,"message":"..."}}`. Flutter should first load `GET /me/deletion` (Accounts module) to display blockers, then discard the access token after confirmed deletion.

### Errors and implementation rules

| HTTP | Case | Flutter action |
|---|---|---|
| 401 | Missing/invalid bearer token | Clear invalid session; navigate to login |
| 422 | Invalid fields / OTP / password / account deletion blockers | Render localized `error.message`, inspect `error.details` when present |
| 429 | Auth throttle / OTP cooldown | Disable retry until server permits; do not loop |
| 200/201 | Successful auth write | Read `data`, not a top-level `token` |
| 204 | Logout | Do not JSON-decode an empty response |

**Source:** [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php), [AuthController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Controllers/AuthController.php), [PhonePasswordResetController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Controllers/PhonePasswordResetController.php), [ProfileController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Controllers/ProfileController.php), [Request rules](https://gitlab.com/alalmiyalhura/outlet/-/tree/main/modules/Identity/Interfaces/Http/Requests). Source inspection: 2026-11-22. **Staging/runtime tests have not been executed.**

## Final Identity contract verification — nested resource, policies and OTP

The following fields were checked directly against the Identity resource, request rules, and policy presenters on `main` (2026-11-22). **These are source contracts, not staging execution results.**

### `UserResource` — complete serialized fields

| Field | Type / nullable | Notes |
|---|---|---|
| `id` | integer | Authenticated user ID |
| `name` | string | User name |
| `email` | string / null | May be absent for phone-only accounts |
| `phone` | string / null | May be absent for email-only accounts |
| `locale` | string | Account language |
| `locale_label` | string | Display label for language |
| `status` | string | Account state; defaults to `active` for an in-memory resource missing the column |
| `email_verified_at` | ISO-8601 string / null | Verification timestamp |
| `phone_verified_at` | ISO-8601 string / null | Verification timestamp |
| `suspension` | object / omitted | Only serialized for suspended users: `kind`, `reason`, `at` |
| `roles` | collection / omitted | Only present when the user model exposes `getRoleNames()` |
| `avatar_url` | string / null | User avatar URL |
| `created_at` | ISO-8601 string / null | Account creation time |

The same resource is returned as `data.user` on successful registration/login, or directly as `data` from `GET /me`, `PATCH /me`, and `POST /me/phone/verify`. **Do not require optional `roles` or `suspension` keys in the Flutter model.**

### Registration and login — exact input constraints

| Field | Register | Login | Validation |
|---|---|---|---|
| `name` | Required | — | String, 2–120 characters |
| `password` | Required | Required | Registration: dynamic policy, max 255, confirmation required; login: required string |
| `password_confirmation` | Required for matching | — | Must equal `password` |
| `phone` | Required in phone mode | Optional alternative identifier | Registration max 30; login max 30; phone normalization also enforced by domain |
| `email` | Required in email mode; optional nullable in phone mode | Optional alternative identifier | RFC email, max 190 at registration; uniqueness excludes pending accounts in email mode |
| `accept_terms` | Required accepted | — | Must be accepted |
| `terms_version` | Optional nullable | — | String, domain max |
| `city_id` | Optional nullable | — | Integer >= 1 |
| `locale` | Optional | — | Enabled locale only |
| `device_name` | Optional | Optional | String, max 100; defaults to `api` |

`login_identifier` is configured server-side. The login request uses `required_without` to accept the alternate email/phone identifier, even when the configured primary identifier differs. In phone-registration mode, `POST /auth/register` returns **201 pending** without a token; `POST /auth/register/verify` requires `phone`, `code`, and the original `password` and returns the authenticated token and user. In email mode registration returns **201** with `data.token` and `data.user` immediately.

### OTP payloads and cooldown

| Object / field | Type | Meaning |
|---|---|---|
| `verification.channel` | string | Usually `sms` |
| `verification.code_length` | integer | Number of OTP input boxes; do not hardcode |
| `verification.expires_in` | integer | Code validity in seconds |
| `verification.resend_in` | integer | Resend countdown in seconds |
| `phone` | string | Normalized phone in code-sent payloads |
| `phone_masked` | string | Safe number for display |
| `subtitle` | string / null | Localized OTP screen instruction |

`POST /auth/register` (phone mode) returns `data.status=pending` plus code-sent fields. `POST /me/phone` returns the code-sent fields without `status`. `POST /auth/register/resend` and `POST /auth/password/phone/request` return `data.message` and `data.verification`. `POST /auth/password/phone/verify` returns `data.reset_token`, **not** a session token. OTP code input is a string and must have exactly the server-configured length. Cooldown errors include `error.details.retry_after` (seconds) and the `Retry-After` HTTP header. An unverified account may produce HTTP **403** with `error.code=account_pending`; show verification rather than treating it as a generic wrong password.

### Password policy, profile and deletion constraints

`GET /auth/password-policy` returns the policy fields together with `helper`, `checklist` (`[{key,label}]`), `breached_hint` (nullable) and `mismatch_message`. Password validation always requires letters and numbers, enforces the configured minimum and maximum 255, and conditionally requires mixed case and rejects compromised passwords according to the active settings. Render the server checklist instead of hardcoding minimum length.

`PATCH /me` supports `name` (2–120), `email` (RFC, max 190, unique excluding self and pending users) and `locale` (enabled). `POST /me/deletion` requires `password` (max 255) and accepts optional `reason` (max **500**). Deletion conditions are rechecked on submission even after `GET /me/deletion` showed `can_delete=true`.

### Example shapes (illustrative values, verified field names)

```json
{"data":{"token":"<opaque-token>","user":{"id":123,"name":"Example User","email":null,"phone":"+9665XXXXXXXX","locale":"ar","locale_label":"العربية","status":"active","email_verified_at":null,"phone_verified_at":"2026-11-22T12:00:00+00:00","avatar_url":null,"created_at":"2026-11-22T11:00:00+00:00"}}}
```

```json
{"data":{"status":"pending","phone":"+9665XXXXXXXX","phone_masked":"+966 5•• ••• XXXX","verification":{"channel":"sms","code_length":4,"expires_in":300,"resend_in":60},"subtitle":"<localized-text>"}}
```

Example OTP durations and values are **illustrative**; the server's active settings are authoritative.

**Verified sources:** [UserResource](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Resources/UserResource.php), [RegisterRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Requests/RegisterRequest.php), [LoginRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Requests/LoginRequest.php), [CodeChallenge](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Application/CodeChallenge.php), [CodeSentView](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Presenters/CodeSentView.php), [OtpCooldownResponse](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/OtpCooldownResponse.php), [PasswordRule](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/Rules/PasswordRule.php), [User domain](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Domain/User.php).

**Identity documentation gate:** all 18 Flutter-facing routes and the previously outstanding user/OTP/password nested contracts have been inspected at source level. **Staging/runtime behavior remains untested.**
