به محتوای اصلی

کلیدها و احراز هویت

دو لایهٔ جدا از هم: کلید API برای برنامهٔ شما، و حساب کاربران نهایی برای آدم‌هایی که از اپ شما استفاده می‌کنند.

کلید API

هر درخواست به API پروژه باید یک کلید همراه داشته باشد:

Authorization: Bearer apck_...

کلید API دسترسی کامل دارد و سقف نرخش همان سقف پلن پروژه است.

  • کلید اصلی — بار اولی که مستندات یا «آزمایش زنده» را باز می‌کنید خودکار ساخته می‌شود. همین کلید داخل نمونه‌کدهای مستندات است و هر وقت بخواهید از صفحهٔ «کلیدهای API» دوباره کپی‌اش می‌کنید.
  • کلیدهایی که خودتان می‌سازید — از دکمهٔ «کلید جدید». هش‌شده نگهداری می‌شوند و مقدارشان فقط همان لحظهٔ ساخت نمایش داده می‌شود؛ همان‌جا کپی کنید.

در همان دیالوگ «کلید جدید» می‌توانید فقط خواندنی را انتخاب کنید: این کلید فقط جدول‌هایی را می‌خواند که در مدل داده «عمومی» کرده‌اید و نمی‌تواند چیزی بنویسد یا پاک کند. برای اپی که فقط داده نمایش می‌دهد امن‌تر است، چون اگر لو برود کسی به بقیهٔ داده‌ها نمی‌رسد. این کلید هم دوباره قابل کپی است.

کلیدهای قدیمی که با apck_play_ شروع می‌شوند هم Production شده‌اند و بدون هیچ تغییری کار می‌کنند.

کلید Production را هرگز در کد فرانت‌اند یا مخزن عمومی نگذارید. برای دسترسی کاربران نهایی از ورود کاربران (JWT) استفاده کنید.

حساب کاربران نهایی (JWT)

اگر اپ شما ثبت‌نام و ورود دارد، لازم نیست خودتان بسازید — هر پروژه موجودیت user و اندپوینت‌های آماده دارد. ثبت‌نام با ایمیل و رمز از همان اول روشن است و تأیید ایمیل ندارد. رمز باید دست‌کم ۸ کاراکتر باشد.

POST https://api.fikaro.ir/{slug}/v1/auth/signup
{ "email": "sara@example.com", "password": "..." }
→ 201 { "user": { "id": "...", "email": "...", "role": "user" },
        "access_token": "eyJ...", "refresh_token": "...", "expires_at": "..." }

POST https://api.fikaro.ir/{slug}/v1/auth/login
{ "email": "sara@example.com", "password": "..." }
→ 200 همان شکل بالا

به‌جای email در ورود می‌شود mobile هم فرستاد، برای کاربری که با کد پیامکی ساخته شده و بعد رمز گذاشته است.

access_token را در همان هدر Authorization بفرستید تا درخواست از طرف آن کاربر انجام شود. این توکن یک ساعت اعتبار دارد؛ وقتی تمام شد، با refresh_token (سی روز اعتبار) از POST /{slug}/v1/auth/refresh توکن تازه بگیرید؛ جوابش همان شکلِ جواب ورود است، با user و یک جفت توکن تازه. کاربر واردشده اطلاعات خودش را از GET /{slug}/v1/auth/me می‌گیرد و با POST /{slug}/v1/auth/logout خارج می‌شود.

در هر درخواست فقط یک اعتبار می‌رود: یا کلید، یا توکن کاربر. مسیرهای auth کلید لازم ندارند، پس صفحه‌ای که فقط کلید فقط‌خواندنی دارد هم می‌تواند کاربر را ثبت‌نام و وارد کند؛ بعد از ورود، درخواست‌ها با توکن همان کاربر فرستاده می‌شوند. کتابخانهٔ @fikaro/client همهٔ این‌ها را خودش انجام می‌دهد، از جمله تازه کردن توکن. نشستِ کاربر در آن به‌طور پیش‌فرض فقط در حافظه‌ی صفحه است و با تازه کردن صفحه از بین می‌رود؛ برای اینکه کاربر وارد بماند، storage: browserStorage() را به createClient بدهید.

اگر اپ شما موبایل است یا درخواست‌ها را خودتان می‌سازید، کل این چرخه — ذخیرهٔ امن توکن، رفرش بعد از 401، خطاهای رفرش و خروج — با curl و کد کامل Flutter، Kotlin، Swift و TypeScript در آموزش ورود و توکن آمده است.

ماندن در حساب: توکن‌ها و خروج۳:۳۸با صدای گوینده و زیرنویسقدم‌ها و متن کامل ویدیو

بعد از ۵ رمز اشتباه برای یک ایمیل، ورود آن ایمیل از همان نشانی اینترنتی ۱۵ دقیقه قفل می‌شود و 429 برمی‌گردد.

ورود با کد پیامکی (OTP)

به‌جای رمز عبور، کاربر می‌تواند با کد یکبار مصرف پیامکی وارد شود. اگر حسابی با آن شماره نباشد، همان تأیید اول حساب را می‌سازد:

POST https://api.fikaro.ir/{slug}/v1/auth/otp/send
{ "mobile": "09XXXXXXXXX" }

POST https://api.fikaro.ir/{slug}/v1/auth/otp/verify
{ "mobile": "09XXXXXXXXX", "code": "482913" }
→ { "user": { ... }, "access_token": "eyJ...", "refresh_token": "..." }

کد ۵ دقیقه اعتبار دارد و بعد از ۳ تلاش اشتباه باطل می‌شود؛ هر شماره در هر ۱۰ دقیقه حداکثر ۳ کد می‌گیرد. هر دو روش ورود از کارت «روش‌های ورود کاربران» پروژه قابل روشن/خاموش کردن‌اند.

هزینهٔ پیامک

پیامک سهمیهٔ ماهانه ندارد و داخل هیچ پلنی نیست. بهای هر ارسال همان لحظه از کیف‌پول شما کم می‌شود، و ماهی که پیامکی نرود هزینه‌ای هم ندارد. قیمت روز در صفحهٔ تعرفه‌ها نوشته شده و مصرف هر پروژه در «پلن و هزینه»ی همان پروژه دیده می‌شود.

یک نکته که بهتر است قبل از راه‌اندازی بدانید: پیامک از اعتبار نقدی کم می‌شود، نه از اعتبار هدیهٔ ثبت‌نام. هدیه برای این است که محصول را امتحان کنید — خرج پلن و زیرساخت خودِ فیکارو می‌شود — ولی پیامک برای ما هزینهٔ واقعی نزد اپراتور دارد و فقط با پولی که از درگاه آمده حساب می‌شود. تفکیک این دو در صفحهٔ «مالی» نوشته شده است.

اگر اعتبار نقدی کفاف ندهد، کد اصلاً فرستاده نمی‌شود و POST /v1/auth/otp/send با 503 و کد sms_unavailable برمی‌گردد. متن این خطا عمداً چیزی از وضعیت مالی شما نمی‌گوید، چون کاربرِ اپ شما نباید صورت‌حساب شما را ببیند — ولی خودتان همان روز اعلان می‌گیرید. بقیهٔ روش‌های ورود و کل API در این حالت دست‌نخورده کار می‌کنند، پس اگر ورود با ایمیل هم روشن باشد کسی بیرون نمی‌ماند.

اگر اپ شما فقط ورود پیامکی دارد، پیش از انتشار یک بار کیف‌پول را شارژ کنید و ورود با ایمیل را هم روشن نگه دارید تا یک کانال، تنها راه ورود کاربرانتان نباشد.

دسترسی «فقط دادهٔ خودم»

این راهنما مربوط به حالت legacy است. هر موجودیت تا فعال‌سازی صریح سیاست در همین حالت می‌ماند. در حالت policy، grantهای همان عملیات مرجع دسترسی‌اند؛ own، all و public قدیمی مجوز دیگری اضافه نمی‌کنند و مقداردهی خودکار مالک این بخش جای شرط check سیاست را نمی‌گیرد.

مناسب سناریوهایی مثل «سفارش‌های من» یا «علاقه‌مندی‌های من». در پنل، روی کارت همان جدول در «جدول‌ها» بزنید و در زبانهٔ «تنظیمات» (در نمای «فهرست»: بخش «نمایش و دسترسی») دو چیز را تنظیم کنید:

  1. فیلد مالکیت — یک فیلد متنی (مثلاً user_id) که شناسهٔ صاحب رکورد در آن می‌نشیند. این فیلد را «الزامی» نکنید: هنگام ساختن رکورد، فیکارو خودش آن را با شناسهٔ کاربرِ واردشده پر می‌کند و هر مقداری که کلاینت فرستاده باشد نادیده گرفته می‌شود.
  2. چه کسی می‌تواند رکوردها را بخواند؟ — «فقط رکوردهای خودِ کاربر». فیلد مالکیت به‌تنهایی فقط ویرایش و حذف را محدود می‌کند؛ بدون این تنظیم، هر کاربر واردشده رکوردهای بقیه را هم می‌خواند.

بعد «ذخیره و اعمال». از این به بعد فهرستِ هر کاربر فقط رکوردهای خودش است (برای دیگران خالی برمی‌گردد، نه خطا)، و خواندن یا تغییر رکوردِ کس دیگر 404 می‌گیرد.

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

سیاست مبتنی بر رابطه

در صفحهٔ «سیاست دسترسی»، نام جدول و فیلدهای مدل خودتان را صریح نگاشت کنید. برای عضویت یا اشتراک، سیاست جدول وابسته را جداگانه بازبینی، ذخیره و فعال کنید؛ الگو هیچ عضویت، نقش یا سهمی در داده ایجاد نمی‌کند. مدیر شرکت یا مدرس یک نقش در رابطهٔ همان رکورد است و اختیار مدیر داخلی پروژه را ندارد.

فیلتر query فقط نتیجهٔ مجاز سرور را محدود می‌کند. هویت از JWT معتبر و وضعیت جاری حساب می‌آید؛ شناسهٔ کاربر در body یا query به کسی اختیار نمی‌دهد. حذف عضویت پس از commit در درخواست بعدی اعمال می‌شود و cursor قدیمی مجوز نیست.

ذخیرهٔ پیش‌نویس دسترسی را تغییر نمی‌دهد. پیش‌نمایش و فعال‌سازی به شناسهٔ دقیق نسخه، schema و نسل جاری وابسته‌اند. بازگشت به نسخهٔ تاریخی نسل تازه می‌سازد؛ بازگرداندن legacy اقدام جداگانه با تأیید صریح است و می‌تواند دسترسی را بیشتر کند.

بیشتر بخوانید