> **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 Settings — Dashboard API handoff

> **Source-verified, not staging-tested.** This document corrects a prior misclassification: pricing endpoints do **not** belong in the Verification module. GitLab repository: `alalmiyalhura/outlet`, branch `main`, reviewed 2026-11-22.

## Scope and access

**Exactly two dashboard endpoints** are registered under `modules/Verification/Routes/api.php`. Both require `auth:sanctum` and the `verification.settings.manage` ability. Base URL `/api/v1`; send `Authorization: Bearer <token>` and `Accept: application/json`. PATCH also requires `Content-Type: application/json`.

The two public OTP endpoints (`POST /verification/request`, `POST /verification/verify`) are documented separately in `flutter/verification.md`; they are not dashboard administration endpoints.

## GET `/api/v1/admin/verification/settings`

**Purpose:** Retrieve the effective OTP configuration. **Request body/query fields:** none. **Success:** HTTP 200.

```http
GET /api/v1/admin/verification/settings HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
```

```json
{
  "data": {
    "otp_length": 4,
    "otp_ttl_seconds": 300,
    "otp_max_attempts": 5,
    "otp_resend_cooldown_seconds": 60
  }
}
```

| Response JSON path | Type | Meaning | Migration default |
|---|---|---|---|
| `data.otp_length` | integer | Digits generated per code | 4 |
| `data.otp_ttl_seconds` | integer | Code lifetime in seconds | 300 |
| `data.otp_max_attempts` | integer | Maximum incorrect attempts per challenge | 5 |
| `data.otp_resend_cooldown_seconds` | integer | Minimum wait between new codes for same target/purpose | 60 |

Values above are **migration defaults**, not guarantees about a configured environment. The response uses the shared `{ "data": ... }` envelope.

**Errors:** `401` without valid authentication; `403` if missing `verification.settings.manage`.

## PATCH `/api/v1/admin/verification/settings`

**Purpose:** Partially update OTP policy. **Success:** HTTP 200, returning the full updated settings object, with the same field types as GET.

### JSON request fields

| Field | Type | Required | Validation | Meaning |
|---|---|---|---|---|
| `otp_length` | integer | No | 4–8 inclusive | Generated OTP digit count |
| `otp_ttl_seconds` | integer | No | 60–3600 inclusive | OTP validity duration |
| `otp_max_attempts` | integer | No | 1–10 inclusive | Wrong-attempt threshold |
| `otp_resend_cooldown_seconds` | integer | No | 0–600 inclusive | Resend wait |

All four fields use Laravel's `sometimes` rule; omitted values are left unchanged. No extra update fields are consumed from validated input. Do not send `null` for these integer fields.

```http
PATCH /api/v1/admin/verification/settings HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

{"otp_length":6,"otp_resend_cooldown_seconds":30}
```

**Illustrative success response:**

```json
{
  "data": {
    "otp_length": 6,
    "otp_ttl_seconds": 300,
    "otp_max_attempts": 5,
    "otp_resend_cooldown_seconds": 30
  }
}
```

### Errors and audit behavior

| HTTP status | Condition | Client behavior |
|---|---|---|
| 401 | Missing/invalid bearer token | Reauthenticate |
| 403 | Authenticated user lacks `verification.settings.manage` | Hide/disable administration UI; do not retry automatically |
| 422 | One or more values violate integer/range constraints | Display `error.details` field messages |

A validation failure has a structured `error.details` object keyed by invalid field; exact localized text is environment-dependent. Successful changes are audited **per changed key** with old/new values and actor; tests verify two audit rows for two changed settings. Settings policy is read for each new OTP issuance, so changes affect newly issued codes, not a guarantee of retroactive alteration of existing challenges.

### Dashboard implementation guidance

1. Load GET before rendering form; populate inputs from actual settings rather than migration defaults.
2. Enforce integer min/max client-side, but treat server `422` as authoritative.
3. Send only modified fields in PATCH and refresh form from returned `data`.
4. Restrict settings UI to authorized users; never expose this route as a Flutter consumer endpoint.
5. Confirm changes on staging, including new-code behavior and audit trail, before operational sign-off.

## Source references

- [Routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Routes/api.php)
- [Admin VerificationSettingsController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Interfaces/Http/Controllers/Admin/VerificationSettingsController.php)
- [VerificationSettings model](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Infrastructure/Settings/VerificationSettings.php)
- [Migration defaults](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Database/Settings/2026_11_19_100000_create_verification_settings.php)
- [VerificationSettingsTest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Verification/Tests/VerificationSettingsTest.php)

**Verification status:** GitLab source and repository tests reviewed; no live HTTP/staging execution performed during this handoff.
