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

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

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

کلید API

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

Authorization: Bearer apck_...

دو نوع کلید از صفحهٔ «کلیدهای API» پروژه ساخته می‌شود:

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

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

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

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

POST /v1/auth/signup
{ "phone": "09XXXXXXXXX", "password": "..." }

POST /v1/auth/login
{ "phone": "09XXXXXXXXX", "password": "..." }
→ { "token": "eyJ..." }

توکن دریافتی را در همان هدر Authorization بفرستید تا درخواست از طرف آن کاربر انجام شود.

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

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

POST /v1/auth/otp/send
{ "mobile": "09XXXXXXXXX" }

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

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

هزینهٔ پیامک

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

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

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

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

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

برای هر موجودیت می‌توانید یک فیلد مالکیت تعیین کنید. وقتی دسترسی روی scope=own باشد، مقدار این فیلد با شناسهٔ کاربرِ واردشده مقایسه می‌شود و هر کاربر فقط رکوردهای خودش را می‌بیند — مناسب سناریوهایی مثل «سفارش‌های من».

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

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