# احراز هویت و ورود دومرحله‌ای

> https://docs.errora.org/account/auth

ارورا افراد را با **شمارهٔ موبایل ایران** می‌شناسد (`09XXXXXXXXX`، که شکل‌های `+98…` و
`0098…` هم به همین قالب یکدست می‌شوند). ایمیل فقط یک فیلد تماس و کانال هشدار است، نه شناسهٔ
ورود.

## ورود دومرحله‌ای (دو گام)

1. **`POST /auth/start`** فقط با شماره. پاسخ می‌گوید حساب `exists` دارد یا نه، `has_password`
   هست یا نه و آیا کد یک‌بارمصرف (`otp_sent`) فرستاده شده است.
2. سپس یکی از این دو:
   - **`POST /auth/login`** با شماره و رمز عبور، یا
   - **`POST /auth/otp/verify`** با شماره و کد شش‌رقمی (کد تازه با
     `POST /auth/otp/request`).

برای شماره‌ای که شناخته نشده، در گام ۱ حساب ساخته می‌شود. حساب پس از کامل‌شدن اولین ورود
**تجهیز** می‌شود: یک سازمان شخصی به‌علاوهٔ اعتبار هدیهٔ ثبت‌نام.

حسابی که رمز عبور ندارد فقط با کد یک‌بارمصرف وارد می‌شود؛ به همین دلیل کدها همیشه در دسترس‌اند.

## توکن‌ها

ورود یک توکن **access** از نوع JWT و یک توکن **refresh** برمی‌گرداند:

```text
Authorization: Bearer <access_token>
POST /auth/refresh    # تبدیل توکن refresh به توکن access تازه
POST /auth/logout
GET  /auth/me
```

برای اسکریپت‌ها، CI و کلاینت‌های MCP به‌جای این‌ها از
[توکن دسترسی شخصی](/account/tokens) استفاده کنید.

## تعیین یا تغییر رمز عبور

```text
POST /auth/password
```

یا در پنل: **پروفایل ← رمز عبور**. داشتن رمز عبور مسیر ورود سریع‌تری می‌دهد و پیش‌نیاز معنادار
فعال‌کردن TOTP است.

## ورود دومرحله‌ای (TOTP)

**پروفایل ← ورود دومرحله‌ای**:

```text
POST /auth/totp/setup     # راز یا آدرس provisioning را برای اسکن برمی‌گرداند
POST /auth/totp/enable    # تأیید با یک کد از اپلیکیشن
POST /auth/totp/disable
```

کد QR را با هر اپلیکیشن احراز هویت (Google Authenticator، Aegis، 1Password) اسکن کنید. پس از
فعال‌سازی، هنگام ورود علاوه بر رمز عبور، کد شش‌رقمی هم خواسته می‌شود.

راه بازگشتی برای خودتان نگه دارید: گم‌شدن اپلیکیشن احراز هویت بدون مسیر بازیابی یعنی باید یک
مدیر، TOTP را برایتان غیرفعال کند.

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| «کد نرسید» | تا پایان زمان انتظار صبر کنید و دوباره درخواست دهید؛ مطمئن شوید شماره یک موبایل معتبر ایران است |
| رمز عبور رد می‌شود ولی مطمئنید درست است | ممکن است حساب اصلاً رمز عبور نداشته باشد؛ با کد یک‌بارمصرف وارد شوید و در **پروفایل** رمز بگذارید |
| شماره شناخته نمی‌شود | شماره به `09XXXXXXXXX` یکدست می‌شود — شکل‌های `+98`/`0098` پذیرفته می‌شوند ولی تلفن ثابت نه |
| با TOTP پشت در مانده‌اید | یک مدیر باید راز TOTP حساب را پاک کند |