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

# Identity / Authentication — endpoint-by-endpoint verified contracts

> Source: repository `main`, Identity Routes, Controllers, Form Requests, UserResource, and Core ApiResponse.
> All paths relative to `/api/v1/`. Sample values are **illustrative**, not live captured responses. Placeholder strings in angle brackets are **not literal API output**.
> Error envelope: `{"error":{"code":"...","message":"...","details":{},"request_id":"..."}}`; only error codes evidenced by sources are stated.
> `data` wrapper applies to ApiResponse; 204 has no JSON body.

## `GET /api/v1/auth/password-policy`

**Authentication:** Public. **Description:** Password policy from active Identity settings; no body.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `—` | None |

**Example request**

```json
{}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "min_length": "integer",
    "requires_letter": "boolean",
    "requires_digit": "boolean",
    "requires_mixed_case": "boolean",
    "rejects_breached": "boolean",
    "helper": "string",
    "checklist": "array<object>",
    "breached_hint": "string|null",
    "mismatch_message": "string"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.min_length` | `string` |
| `data.requires_letter` | `string` |
| `data.requires_digit` | `string` |
| `data.requires_mixed_case` | `string` |
| `data.rejects_breached` | `string` |
| `data.helper` | `string` |
| `data.checklist` | `string` |
| `data.breached_hint` | `string` |
| `data.mismatch_message` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `GET /api/v1/auth/otp-policy`

**Authentication:** Public. **Description:** OTP metadata comes from runtime settings.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `—` | None |

**Example request**

```json
{}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "channel": "string",
    "code_length": "integer",
    "expires_in": "integer",
    "resend_in": "integer"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.channel` | `string` |
| `data.code_length` | `string` |
| `data.expires_in` | `string` |
| `data.resend_in` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/register`

**Authentication:** Public. **Description:** 201; response depends on configured login_identifier; illustrative values.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `name` | name: required string min User::MIN_NAME max User::MAX_NAME |
| `password` | password: required PasswordRule confirmed |
| `password_confirmation` | password_confirmation: required for confirmation |
| `accept_terms` | accept_terms: accepted |
| `phone` | phone: required string max30 in phone mode |
| `email` | email: required email:rfc max190 unique in email mode, optional nullable max190 in phone mode |
| `locale` | locale: optional enabled locale |
| `device_name` | device_name: optional string max100 |
| `terms_version` | terms_version: optional nullable string max TermsAcceptance::MAX_VERSION |
| `city_id` | city_id: optional nullable integer min1 |

**Example request**

```json
{
  "name": "Ahmed Ali",
  "phone": "+966501234567",
  "password": "<strong-password>",
  "password_confirmation": "<strong-password>",
  "accept_terms": true,
  "city_id": 1
}
```

**Example success response**

HTTP 201

```json
{
  "data": {
    "phone_mode": {
      "status": "pending",
      "phone": "+966501234567",
      "phone_masked": "<masked-phone>",
      "verification": {
        "channel": "sms",
        "code_length": "<configured integer>",
        "expires_in": "<configured seconds>",
        "resend_in": "<configured seconds>"
      },
      "subtitle": "<localized text>"
    },
    "email_mode": {
      "token": "<sanctum-access-token>",
      "user": {
        "id": 42,
        "name": "Ahmed Ali",
        "email": null,
        "phone": "+966501234567",
        "locale": "ar",
        "locale_label": "العربية",
        "status": "active",
        "email_verified_at": null,
        "phone_verified_at": null,
        "avatar_url": null,
        "created_at": "2026-11-22T10:00:00+00:00"
      }
    }
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.phone_mode` | `object` |
| `data.phone_mode.status` | `string` |
| `data.phone_mode.phone` | `string` |
| `data.phone_mode.phone_masked` | `string` |
| `data.phone_mode.verification` | `object` |
| `data.phone_mode.verification.channel` | `string` |
| `data.phone_mode.verification.code_length` | `string` |
| `data.phone_mode.verification.expires_in` | `string` |
| `data.phone_mode.verification.resend_in` | `string` |
| `data.phone_mode.subtitle` | `string` |
| `data.email_mode` | `object` |
| `data.email_mode.token` | `string` |
| `data.email_mode.user` | `object` |
| `data.email_mode.user.id` | `integer` |
| `data.email_mode.user.name` | `string` |
| `data.email_mode.user.email` | `null` |
| `data.email_mode.user.phone` | `string` |
| `data.email_mode.user.locale` | `string` |
| `data.email_mode.user.locale_label` | `string` |
| `data.email_mode.user.status` | `string` |
| `data.email_mode.user.email_verified_at` | `null` |
| `data.email_mode.user.phone_verified_at` | `null` |
| `data.email_mode.user.avatar_url` | `null` |
| `data.email_mode.user.created_at` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/register/verify`

**Authentication:** Public. **Description:** 200; only phone registration verification.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required string max30 |
| `code` | code: required string digits:configured OTP length |
| `password` | password: required string max255 |
| `device_name` | device_name: optional string max100 |

**Example request**

```json
{
  "phone": "+966501234567",
  "code": "1234",
  "password": "<password-used-on-register>"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "token": "<sanctum-access-token>",
    "user": {
      "id": 42,
      "name": "Ahmed Ali",
      "email": null,
      "phone": "+966501234567",
      "locale": "ar",
      "locale_label": "العربية",
      "status": "active",
      "email_verified_at": null,
      "phone_verified_at": null,
      "avatar_url": null,
      "created_at": "2026-11-22T10:00:00+00:00"
    }
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.token` | `string` |
| `data.user` | `object` |
| `data.user.id` | `integer` |
| `data.user.name` | `string` |
| `data.user.email` | `null` |
| `data.user.phone` | `string` |
| `data.user.locale` | `string` |
| `data.user.locale_label` | `string` |
| `data.user.status` | `string` |
| `data.user.email_verified_at` | `null` |
| `data.user.phone_verified_at` | `null` |
| `data.user.avatar_url` | `null` |
| `data.user.created_at` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/register/resend`

**Authentication:** Public. **Description:** 200; timing values illustrative and configured.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required string max30 |

**Example request**

```json
{
  "phone": "+966501234567"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "message": "<localized registration_code_resent>",
    "verification": {
      "channel": "sms",
      "code_length": 4,
      "expires_in": 300,
      "resend_in": 60
    }
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.message` | `string` |
| `data.verification` | `object` |
| `data.verification.channel` | `string` |
| `data.verification.code_length` | `integer` |
| `data.verification.expires_in` | `integer` |
| `data.verification.resend_in` | `integer` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/login`

**Authentication:** Public. **Description:** 200; email alternative supported; app token not dashboard token.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required_without:email when phone-first, otherwise optional nullable string max30 |
| `email` | email: required_without:phone when email-first, otherwise optional email |
| `password` | password: required string |
| `device_name` | device_name: optional string max100 |

**Example request**

```json
{
  "phone": "+966501234567",
  "password": "<password>",
  "device_name": "flutter"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "token": "<sanctum-access-token>",
    "user": {
      "id": 42,
      "name": "Ahmed Ali",
      "email": null,
      "phone": "+966501234567",
      "locale": "ar",
      "locale_label": "العربية",
      "status": "active",
      "email_verified_at": null,
      "phone_verified_at": null,
      "avatar_url": null,
      "created_at": "2026-11-22T10:00:00+00:00"
    }
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.token` | `string` |
| `data.user` | `object` |
| `data.user.id` | `integer` |
| `data.user.name` | `string` |
| `data.user.email` | `null` |
| `data.user.phone` | `string` |
| `data.user.locale` | `string` |
| `data.user.locale_label` | `string` |
| `data.user.status` | `string` |
| `data.user.email_verified_at` | `null` |
| `data.user.phone_verified_at` | `null` |
| `data.user.avatar_url` | `null` |
| `data.user.created_at` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/password/forgot`

**Authentication:** Public. **Description:** 200; same response whether account exists or not.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `email` | email: required email |

**Example request**

```json
{
  "email": "ahmed@example.com"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "message": "<localized reset_link_sent>"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.message` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/password/reset`

**Authentication:** Public. **Description:** 200; invalid token raises invalid_reset_token.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `token` | token: required string |
| `email` | email: required email |
| `password` | password: required PasswordRule confirmed |
| `password_confirmation` | password_confirmation: confirmation |

**Example request**

```json
{
  "token": "<reset-token>",
  "email": "ahmed@example.com",
  "password": "<new-password>",
  "password_confirmation": "<new-password>"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "message": "<localized password_reset>"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.message` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/password/phone/request`

**Authentication:** Public. **Description:** 200; verification timing illustrative.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required string max30 |

**Example request**

```json
{
  "phone": "+966501234567"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "message": "<localized reset_code_sent>",
    "verification": {
      "channel": "sms",
      "code_length": 4,
      "expires_in": 300,
      "resend_in": 60
    }
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.message` | `string` |
| `data.verification` | `object` |
| `data.verification.channel` | `string` |
| `data.verification.code_length` | `integer` |
| `data.verification.expires_in` | `integer` |
| `data.verification.resend_in` | `integer` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/password/phone/verify`

**Authentication:** Public. **Description:** 200.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required string max30 |
| `code` | code: required string digits:configured OTP length |
| `device_name` | device_name: optional string max100 |

**Example request**

```json
{
  "phone": "+966501234567",
  "code": "1234"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "reset_token": "<reset-ticket>"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.reset_token` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/password/phone/reset`

**Authentication:** Public. **Description:** 200.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `reset_token` | reset_token: required string max2000 |
| `password` | password: required PasswordRule confirmed |
| `password_confirmation` | password_confirmation: confirmation |

**Example request**

```json
{
  "reset_token": "<reset-ticket>",
  "password": "<new-password>",
  "password_confirmation": "<new-password>"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "message": "<localized password_reset>"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.message` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/logout`

**Authentication:** Bearer Sanctum. **Description:** 204; no body; deletes current token.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `—` | No request body |

**Example request**

```json
{}
```

**Example success response**

HTTP 204

No response body.

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/auth/logout-all`

**Authentication:** Bearer Sanctum. **Description:** 204; no body; deletes all user tokens.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `—` | No request body |

**Example request**

```json
{}
```

**Example success response**

HTTP 204

No response body.

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `GET /api/v1/me`

**Authentication:** Bearer Sanctum. **Description:** 200; roles and suspension conditionally included.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `—` | No request body |

**Example request**

```json
{}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "id": 42,
    "name": "Ahmed Ali",
    "email": null,
    "phone": "+966501234567",
    "locale": "ar",
    "locale_label": "العربية",
    "status": "active",
    "email_verified_at": null,
    "phone_verified_at": null,
    "avatar_url": null,
    "created_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.id` | `integer` |
| `data.name` | `string` |
| `data.email` | `null` |
| `data.phone` | `string` |
| `data.locale` | `string` |
| `data.locale_label` | `string` |
| `data.status` | `string` |
| `data.email_verified_at` | `null` |
| `data.phone_verified_at` | `null` |
| `data.avatar_url` | `null` |
| `data.created_at` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `PATCH /api/v1/me`

**Authentication:** Bearer Sanctum. **Description:** 200; returns refreshed UserResource.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `name` | name: optional required string min User::MIN_NAME max User::MAX_NAME |
| `email` | email: optional email:rfc max190 unique except current and pending |
| `locale` | locale: optional enabled locale |

**Example request**

```json
{
  "name": "Ahmed Updated",
  "locale": "ar"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "id": 42,
    "name": "Ahmed Updated",
    "email": null,
    "phone": "+966501234567",
    "locale": "ar",
    "locale_label": "العربية",
    "status": "active",
    "email_verified_at": null,
    "phone_verified_at": null,
    "avatar_url": null,
    "created_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.id` | `integer` |
| `data.name` | `string` |
| `data.email` | `null` |
| `data.phone` | `string` |
| `data.locale` | `string` |
| `data.locale_label` | `string` |
| `data.status` | `string` |
| `data.email_verified_at` | `null` |
| `data.phone_verified_at` | `null` |
| `data.avatar_url` | `null` |
| `data.created_at` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/me/phone`

**Authentication:** Bearer Sanctum. **Description:** 200; OTP settings illustrative; new phone must differ from existing.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required string max30 |

**Example request**

```json
{
  "phone": "+966501234567"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "phone": "+966501234567",
    "phone_masked": "<masked-phone>",
    "verification": {
      "channel": "sms",
      "code_length": 4,
      "expires_in": 300,
      "resend_in": 60
    },
    "subtitle": "<localized text>"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.phone` | `string` |
| `data.phone_masked` | `string` |
| `data.verification` | `object` |
| `data.verification.channel` | `string` |
| `data.verification.code_length` | `integer` |
| `data.verification.expires_in` | `integer` |
| `data.verification.resend_in` | `integer` |
| `data.subtitle` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/me/phone/verify`

**Authentication:** Bearer Sanctum. **Description:** 200; returns refreshed UserResource.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `phone` | phone: required string max30 |
| `code` | code: required string digits:configured OTP length |

**Example request**

```json
{
  "phone": "+966501234567",
  "code": "1234"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "id": 42,
    "name": "Ahmed Ali",
    "email": null,
    "phone": "+966501234567",
    "locale": "ar",
    "locale_label": "العربية",
    "status": "active",
    "email_verified_at": null,
    "phone_verified_at": null,
    "avatar_url": null,
    "created_at": "2026-11-22T10:00:00+00:00"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.id` | `integer` |
| `data.name` | `string` |
| `data.email` | `null` |
| `data.phone` | `string` |
| `data.locale` | `string` |
| `data.locale_label` | `string` |
| `data.status` | `string` |
| `data.email_verified_at` | `null` |
| `data.phone_verified_at` | `null` |
| `data.avatar_url` | `null` |
| `data.created_at` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)

## `POST /api/v1/me/deletion`

**Authentication:** Bearer Sanctum. **Description:** 200; deletion blockers can yield 422 account_deletion_blocked.

**Request fields / validation**

| Field / rule | Type / required / validation |
|---|---|
| `password` | password: required string max255 |
| `reason` | reason: optional nullable string max User::MAX_DELETION_REASON |

**Example request**

```json
{
  "password": "<current-password>",
  "reason": "<optional reason>"
}
```

**Example success response**

HTTP 200

```json
{
  "data": {
    "deleted": true,
    "message": "<localized account_deleted>"
  }
}
```

**Response field types**

| Field | Type |
|---|---|
| `data.deleted` | `boolean` |
| `data.message` | `string` |

**Source references:**
- [Identity routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Routes/api.php)
- [Identity HTTP controllers / requests](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Identity/Interfaces/Http/)
