API: احراز هویت

این نقاط پایانی نشست می‌سازند و پایان می‌دهند و یک توکن Bearer برمی‌گردانند که دقیقاً مثل کلید API استفاده می‌شود. برای اسکریپت‌های بدون‌مراقب، به‌جای توکن ورود از یک کلید API جداگانه استفاده کنید.

ثبت‌نام

POST /auth/register

حساب می‌سازد و یک کد ۶ رقمی با ایمیل و پیامک می‌فرستد. شماره باید موبایل ایرانی باشد و terms_accepted باید true باشد.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 201 ایجاد شد. برمی‌گرداند: message (string), user_id (integer), otp_channel (string).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/register \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-name","email":"you@example.com","phone":"09121234567","password":"your-password","terms_accepted":true}'

تأیید کد ثبت‌نام

POST /auth/verify-otp

کد را تأیید می‌کند و کاربر را همراه با یک توکن Bearer برمی‌گرداند.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق. برمی‌گرداند: user (User), token (string), dashboard (string).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/verify-otp \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1,"code":"123456"}'

ارسال مجدد کد ثبت‌نام

POST /auth/resend-otp

یک کد تأیید تازه می‌فرستد.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/resend-otp \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1}'

ورود

POST /auth/login

ایمیل و رمز را بررسی می‌کند. بدون احراز هویت دومرحله‌ای کاربر و توکن برمی‌گرداند. اگر فعال باشد requires_2fa و یک challenge_token مبهم برای مرحلهٔ بعد (۵ دقیقه اعتبار، ۵ تلاش) برمی‌گرداند. حساب‌هایی که تأیید ثبت‌نام را کامل نکرده‌اند خطای email_not_verified می‌گیرند.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

تکمیل ورود دومرحله‌ای

POST /auth/login/2fa

challenge_token مرحلهٔ ورود و کد ۶ رقمی فعلی (برنامهٔ احراز هویت، ایمیل یا پیامک) را می‌گیرد و کاربر و توکن برمی‌گرداند. پنج تلاش نادرست چالش را باطل می‌کند.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق. برمی‌گرداند: user (User), token (string), dashboard (string).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/login/2fa \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"string","code":"123456"}'

ارسال مجدد کد دومرحله‌ای

POST /auth/login/2fa/resend

برای حساب‌هایی که ایمیل یا پیامک را عامل دوم دارند کد جدید می‌فرستد.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق. برمی‌گرداند: message (string), expires_in_minutes (integer).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/login/2fa/resend \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"string"}'

درخواست لینک بازیابی رمز

POST /auth/forgot-password

اگر آدرس متعلق به حسابی باشد لینک بازیابی را ایمیل می‌کند. پاسخ در هر دو حالت یکسان است.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق. برمی‌گرداند: message (string).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/auth/forgot-password \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

تعیین رمز عبور جدید

POST /auth/reset-password

با توکن ایمیل‌شده رمز جدید تعیین می‌کند. همهٔ نشست‌های موجود خارج می‌شوند.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق. برمی‌گرداند: message (string).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/auth/reset-password \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","token":"TOKEN_FROM_EMAIL","password":"your-password","password_confirmation":"your-new-password"}'

خروج

POST /auth/logout

توکنی را که با آن درخواست زده‌اید باطل می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

• 200 موفق

نمونه

curl -X POST https://veneshcloud.ir/api/auth/logout \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

کاربر فعلی

GET /auth/me

حسابِ مالک توکن را برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

• 200 موفق. برمی‌گرداند User.

نمونه

curl -X GET https://veneshcloud.ir/api/auth/me \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

ورود با کد بازیابی

POST /account/2fa/recovery-code

ورود دومرحله‌ای را با یکی از کدهای بازیابی یک‌بارمصرف همراه challenge_token مرحلهٔ ورود کامل می‌کند.

احراز هویت: ندارد، این نقطهٔ پایانی عمومی است.

بدنهٔ درخواست (application/json)

پاسخ‌ها

• 200 موفق. برمی‌گرداند: user (User), token (string), dashboard (string).
• 422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
• 429 درخواست‌های بیش از حد

نمونه

curl -X POST https://veneshcloud.ir/api/account/2fa/recovery-code \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"string","recovery_code":"RECOVERY_CODE"}'

اشیاء

فهرست فیلدهای اشیایی که در بالا برگردانده می‌شوند.

User