> **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.

# Verification — Flutter API handoff (source-reviewed)

**Base path:** `/api/v1` · **Module:** `modules/Verification` · **Branch reviewed:** `main` · **Reviewed:** 2026-11-22 · **Coverage:** 2/2 Flutter/public routes.

> These are repository-derived contracts, **not** captured staging responses. This generic Verification module is separate from Identity's `/auth/register/verify` phone registration flow. Do not interchange their OTPs or proof tokens without a consuming endpoint explicitly supporting them.

## Shared rules

| Item | Contract |
|---|---|
| Authentication | Both endpoints are **public**, no bearer token required |
| Request format | JSON with `Content-Type: application/json`; `Accept: application/json` recommended |
| Throttling | Both routes use `throttle:auth`; HTTP `429` possible; exact dynamic rate not specified here |
| Successful response | `ApiResponse::ok(...)`: `{"data": ...}` with HTTP `200` |
| Validation | Laravel FormRequest, typically HTTP `422`; error-envelope details must be checked against shared exception handling |
| OTP configuration | Length, TTL, attempts and resend cooldown come from admin settings, not constants in the app |
| Proof lifetime | `verification.proof_ttl_seconds`, default **900 seconds** (environment-configurable) |
| Channels | `email` in base config; `sms` only if another module registers it in `extra_channels` |

## 1. `POST /api/v1/verification/request`

**Purpose:** Request an OTP challenge for a particular `target` and `purpose`. **Authentication:** none. **Success:** `200 OK`.

### Request body — field-by-field

| JSON field | Type | Required | Validation / semantics |
|---|---|---|---|
| `channel` | string | Yes | Must be in `verification.channels + verification.extra_channels`; base channel is `email`, optional integrations can add `sms` |
| `target` | string | Yes | Max 190 characters; for `sms`, E.164-style `^\\+[1-9]\\d{6,14}$` |
| `purpose` | string | Yes | Max 60 characters, lowercase ASCII letters/digits plus `_`, `.`, `-`; regex `^[a-z0-9_.-]+$` |

**Example (email channel):**

```http
POST /api/v1/verification/request HTTP/1.1
Accept: application/json
Content-Type: application/json

{"channel":"email","target":"person@example.com","purpose":"signup"}
```

### Success response — field-by-field

```json
{"data":{"message":"If the target is valid, a code was sent."}}
```

| JSON path | Type | Meaning |
|---|---|---|
| `data` | object | Standard successful API envelope |
| `data.message` | string | Generic message, deliberately does **not** disclose whether an account/target exists |

### Errors and behavior

| Condition | HTTP / error | Flutter action |
|---|---|---|
| Missing/invalid channel, target or purpose | Usually `422` validation | Show field error; for SMS validate E.164 before sending |
| Requested again before configured cooldown | Business error `challenge_cooldown`; HTTP status depends on shared exception renderer | Show resend countdown; do not hardcode a duration |
| API throttle | `429` | Back off, avoid repeated requests |

The handler normalizes `target` by trimming and lowercasing it, checks the last issuance for that target/purpose, replaces the active challenge, then asks the configured sender to send the code. **The response does not include the OTP, expiry, or cooldown numbers.** The app should not invent these from the response.

## 2. `POST /api/v1/verification/verify`

**Purpose:** Check an OTP and return a short-lived, encrypted proof for a downstream workflow. **Authentication:** none. **Success:** `200 OK`.

### Request body — field-by-field

| JSON field | Type | Required | Validation / semantics |
|---|---|---|---|
| `target` | string | Yes | Max 190 characters; must match the target used to request the challenge (handler trims/lowercases) |
| `purpose` | string | Yes | Max 60 characters; `^[a-z0-9_.-]+$`; must match challenge purpose |
| `code` | string | Yes | 4–10 digits by HTTP validation; actual issued length is configured between 4 and 8 digits; **keep leading zeros** |

```http
POST /api/v1/verification/verify HTTP/1.1
Accept: application/json
Content-Type: application/json

{"target":"person@example.com","purpose":"signup","code":"012345"}
```

### Success response — field-by-field

```json
{"data":{"verified":true,"proof":"<opaque-encrypted-proof>"}}
```

| JSON path | Type | Meaning |
|---|---|---|
| `data.verified` | boolean | `true` on successful verification |
| `data.proof` | string | Opaque encrypted proof bound to normalized target and purpose, expiring according to `proof_ttl_seconds` |

### Errors and behavior

| Condition | HTTP / error | Flutter action |
|---|---|---|
| Missing/malformed request fields | Usually `422` validation | Show input validation errors |
| Incorrect, expired, absent or previously used code | Business error `invalid_code`; HTTP status determined by shared exception renderer | Show generic invalid/expired message; allow a new challenge when appropriate |
| Too many incorrect attempts | Business error `challenge_locked` from domain | Request a new code; don't keep retrying same challenge |
| API throttle | `429` | Back off |

The verify handler persists the attempt count even after a wrong code. A successful response issues the proof through Laravel encryption; Flutter must **treat it as an opaque secret**, never parse, modify, log, or assume it is a JWT. A downstream API must explicitly accept the proof and verify the **same target and purpose**; possession of a proof does not automatically authenticate the user.

## Flutter implementation handoff

1. Use the relevant business flow's `purpose`; do not invent a purpose value if the consuming feature has not specified one.
2. Choose an enabled channel; do not assume SMS is available just because a phone number is entered.
3. Send `POST /verification/request`, show a generic confirmation, and begin a resend UX without claiming a server-specified countdown from this response.
4. Preserve the OTP as a **string** (leading zeros), submit `target`, `purpose`, and `code` to `/verification/verify`.
5. On `verified: true`, pass `proof` only to the specific downstream API that documents support for it. Never store it in analytics or error logs.
6. Handle invalid codes, cooldown, attempt lockout, throttle, expiry, offline and retry without disclosing account existence.

### Dart model sketches

```dart
class VerificationResult {
  final bool verified;
  final String proof;
  VerificationResult.fromJson(Map<String, dynamic> json)
      : verified = json['verified'] as bool,
        proof = json['proof'] as String;
}

// Response JSON: { "data": { "verified": true, "proof": "..." } }
final data = responseJson['data'] as Map<String, dynamic>;
final result = VerificationResult.fromJson(data);
```

## Source traceability and verification boundary

- [Routes/api.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Routes/api.php) — exact paths, public access and throttle.
- [VerificationController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Interfaces/Http/Controllers/VerificationController.php) — success payload and `invalid_code`.
- [RequestCodeRequest.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Interfaces/Http/Requests/RequestCodeRequest.php) and [CheckCodeRequest.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Interfaces/Http/Requests/CheckCodeRequest.php) — exact request validation.
- [IssueChallengeHandler.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Application/Issue/IssueChallengeHandler.php), [VerifyChallengeHandler.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Application/Verify/VerifyChallengeHandler.php) — issuance, cooldown and verification.
- [SettingsChallengePolicy.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Infrastructure/Settings/SettingsChallengePolicy.php) — dynamic OTP policy.
- [VerificationProof.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Infrastructure/VerificationProof.php) and [Config/verification.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Config/verification.php) — proof security and TTL.

**Not executed:** live/staging requests, actual email/SMS delivery, exact global business-exception HTTP mapping, proof consumption by downstream APIs. These need separate integration verification; source-reviewed does not mean end-to-end tested.
