---
feature: Account, login, profile
slug: account
surface: provider
consumer: vue
version: 1.1.2
status: ready
brd_version: "v1.0 (11-8-2026) + additional requirements"
brd_ids: [HPV-001, HPV-002, HPV-016]
business_rules: [BR-HALL-01, BR-HALL-02]
decisions: [TD-08, TD-14, TD-21]
schema_tables: [hall_providers, hall_provider_translations, users]
related_docs: [halls.md, ../admin/hall-providers.md]
last_updated: 2026-11-15
---

# Account, login, profile — Provider Dashboard Integration Guide

> **Base URL:** `{HOST}/api/v1/provider` · Shared rules: [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Quick reference

| | |
|---|---|
| Version | 1.1.2 (2026-11-15) — docs: permissions model, logo upload hash; dashboard action: none |
| Status | ready · BRD HPV-001, HPV-002 (HPV-016 is completed feature by feature) · TD-08 |
| Auth | Login is public; everything else needs the provider's Bearer token. A token of another surface gets 403. |

| Method | Path | Route name | Purpose |
|--------|------|------------|---------|
| `POST` | `/auth/login` | `provider.auth.login` | Phone or email + password → token |
| `POST` | `/auth/forgot-password` | `provider.auth.forgot` | Send a reset code to the phone or email |
| `POST` | `/auth/reset-password` | `provider.auth.reset` | Code + new password |
| `POST` | `/auth/logout` | `provider.auth.logout` | Revoke the token |
| `GET` | `/profile` | `provider.profile.show` | Basic data |
| `PUT` | `/profile` | `provider.profile.update` | Edit basic data (partial) |

**Statuses:** provider `active` / `inactive`; entity type `hotel` / `exhibition_venue` / `other`.
**Error codes:** `ACCOUNT_INACTIVE` (403, suspended) · `BUSINESS_RULE_VIOLATED` (suspended provider using an old token).
**Open decisions:** None. The admin screens that create and suspend providers (ADM-015) are not built yet; until then provider rows are created by seeders.

## 1. Business summary

There is no self-registration (BR-HALL-02). The admin creates the account after the external contract and the provider logs in with the credentials it receives. A suspended provider cannot log in and cannot use a token issued earlier; its data and past bookings are kept. The provider edits its own basic data but never its status.

## 2. Login

`POST /api/v1/provider/auth/login` — body `{ "login": "<phone or email>", "password": "<string>" }`. A phone may be typed with or without the country code or a leading 0 (`501234567`, `0501234567`, `+966501234567`). Failed attempts are throttled per login + IP (429 with `Retry-After`).

**Request payload (`POST /auth/login`):**

```json
{
  "login": "provider@info.com",
  "password": "Password123!"
}
```

**Captured response:**

```json
{
  "status": "success",
  "message": "You logged in successfully",
  "data": {
    "id": 7,
    "name": "Provider",
    "email": "provider@info.com",
    "phone_code": "966",
    "phone": "500000007",
    "country": {
      "id": 1,
      "name": "المملكة العربية السعودية",
      "code": "966",
      "flag": "https://ui-avatars.com/api/?name=🏳&background=e5e7eb&color=6b7280&size=128",
      "phone_length": 9,
      "phone_starting_number": "5"
    },
    "image": "https://ui-avatars.com/api/?name=U&background=dbeafe&color=1d4ed8&size=200",
    "user_type": "Provider",
    "is_active": true,
    "is_verified": true,
    "is_banned": false,
    "is_suspended": false,
    "settings": {
      "locale": "ar",
      "allow_notifications": true
    },
    "location": {
      "lat": null,
      "lng": null
    },
    "token": "<jwt-token-redacted>",
    "verification_token": null,
    "permissions": []
  }
}
```

Suspended:

```json
{"status":"fail","message":"Your account is suspended, contact the administrator.","data":{"error_code":"ACCOUNT_INACTIVE"}}
```

## 2a. Forgot and reset password

`POST /auth/forgot-password` — `{ "login": "<phone or email>" }` → `{ "verification_token": "<uuid>" }`. The answer is the same whether or not the account exists. A 4-digit code is sent to that phone or email (fixed `1111` until the SMS provider is connected).

`POST /auth/reset-password` — `{ "token", "code", "password" (min 8), "password_confirmation" }` → `Password reset successfully.` Every token issued before the reset stops working. A wrong or expired code, a token not issued by this flow, or a token already used is a 422.

## 3. Profile

`GET /profile` — every key is always present.

**Captured response:**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "a33b175f-2079-42d9-8c49-516e76a9c98f",
    "name": "مقدم القاعات التجريبي",
    "description": null,
    "entity_type": {
      "value": "hotel",
      "label": "فندق"
    },
    "status": {
      "value": "active",
      "label": "نشط"
    },
    "city": {
      "id": "a33b175a-65be-475b-81d5-60cbdda2139a",
      "name": "الرياض"
    },
    "address": null,
    "contact_phone": null,
    "email": "provider@info.com",
    "logo": "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200",
    "translations": {
      "ar": {
        "name": "مقدم القاعات التجريبي",
        "description": null
      },
      "en": {
        "name": "Demo Hall Provider",
        "description": null
      }
    }
  }
}
```

`PUT /profile` — every field is `sometimes`; `status` is ignored.

**Request payload (`PUT /profile`):**

```json
{
  "city_id": "a33b175a-65be-475b-81d5-60cbdda2139a",
  "address": "طريق الملك فهد، حي العليا",
  "contact_phone": "0112345678",
  "entity_type": "hotel",
  "ar": {
    "name": "مقدم القاعات التجريبي",
    "description": "قاعات مجهزة بأحدث التقنيات."
  },
  "en": {
    "name": "Demo Hall Provider",
    "description": "Halls equipped with modern technologies."
  }
}
```

| Field | Validation |
|-------|-----------|
| `ar.name`, `en.name` | string, max 255 |
| `ar.description`, `en.description` | nullable string, max 2000 |
| `entity_type` | `hotel` · `exhibition_venue` · `other` |
| `city_id` | uuid of an active city |
| `address` | nullable string, max 1000 |
| `contact_phone` | nullable string, max 30 |
| `logo` | the `data.hash` returned by `POST /api/v1/client/upload` (see `API_CONVENTIONS.md` → *Media upload*) |

## 3a. Types

```ts
export interface ProviderProfile {
  id: string; name: string; description: string | null;
  entity_type: EnumValue<'hotel' | 'exhibition_venue' | 'other'>;
  status: EnumValue<'active' | 'inactive'>;
  city: { id: string; name: string } | null;
  address: string | null; contact_phone: string | null; email: string | null; logo: string;
  translations: Record<'ar' | 'en', { name: string; description: string | null }>;
}
```

## 4. Business rules enforced

| Rule | Behaviour |
|------|-----------|
| BR-HALL-01/02 | No registration route exists. |
| HPV-001 | Suspended (provider or login account inactive) → no login; an old token is refused with 422 `BUSINESS_RULE_VIOLATED` on every provider endpoint. |
| TD-08, TD-21 | Credentials are matched among provider accounts only, so a trainer, client or admin with the same phone or email cannot log in here (422 as for a wrong password); their tokens get 403 on every provider endpoint. |

## 5. Known limitations

- **Permissions:** the provider app has no roles. One account is one provider with full access to its own data, so `permissions` is always `[]` and the dashboard must not gate screens on it. A suspended provider is refused at login and on every call (HPV-001). Roles for provider staff are not in the BRD.
- `data.id` in the login response is the integer user id (shared `LoginResource`, legacy gap, not the uuid rule of TD-14).
- Empty `logo` returns the placeholder URL required by the conventions.

## Version history

| Version | Date | Type | Summary | Dashboard action required |
|---------|------|------|---------|---------------------------|
| 1.1.2 | 2026-11-15 | DOCS | Permissions model stated (none; `permissions` is always `[]`); logo takes the upload `hash`. | None. |
| 1.1.1 | 2026-11-15 | PATCH | The forgot-password `verification_token` is a plain uuid (was `reset:<uuid>`, too long for MySQL). Opaque; send it back unchanged. | None. |
| 1.1.0 | 2026-11-15 | MINOR | Login accepts a phone as well as an email; forgot / reset password; a foreign account now gets 422 instead of 403 at login. | Add the phone option and the reset screens. |
| 1.0.0 | 2026-11-15 | Initial | Login, logout, profile show/update. | Integrate as described above. |

## Changelog

### 1.1.0 — 2026-11-15
- **Added:** `auth/forgot-password`, `auth/reset-password`; phone login (DEC-14); `SurfaceCredentials`, `SurfacePasswordReset`.
- **Changed:** login looks the account up inside the provider type only (TD-21); a trainer / client / admin account at provider login is a 422, not a 403.
- **Breaking:** No
- **Dashboard action required:** Add the phone option to the login form and build the reset screens.
- **BRD / decisions:** HPV-001, DEC-14, TD-21

### 1.0.0 — 2026-11-15
- **Added:** `auth/login`, `auth/logout`, `profile` (GET, PUT); `ProviderAccountIsOpen` rule.
- **Breaking:** No
- **Dashboard action required:** Integrate login and profile.
- **BRD / decisions:** HPV-001, HPV-002, BR-HALL-01, BR-HALL-02, TD-08
