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

آموزش ورود و توکن، قدم به قدم

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

برای همهٔ این کارها لازم نیست کد سمت سرور بنویسید؛ اندپوینت‌ها روی هر پروژه آماده‌اند. کاری که می‌ماند، سمت کلاینت است، و بیشتر اشتباه‌ها هم همان‌جا اتفاق می‌افتد. در مثال‌ها اسلاگ پروژه my-app است؛ اسلاگ پروژهٔ خودتان را جایش بگذارید.

کلید API و توکن کاربر دو چیز جدا هستند. کلید مال برنامهٔ شماست و دسترسی کامل دارد؛ توکن مال یک کاربر است و فقط کاری را می‌کند که آن کاربر اجازه دارد. فرقشان در کلیدها و احراز هویت آمده است.

همین چرخه را در این ویدیو، درخواست به درخواست و با جواب‌های واقعی سرور ببینید:

ورود و توکن، از ترمینال۴:۰۸با صدای گوینده و زیرنویسقدم‌ها و متن کامل ویدیو

دو توکن، دو کار

ورود موفق دو توکن برمی‌گرداند:

access_tokenrefresh_token
کارشهمراه هر درخواست می‌رود و می‌گوید کاربر کیستفقط برای گرفتن توکن‌های تازه
اعتباریک ساعتسی روز از آخرین رفرش
کجا فرستاده می‌شودهدر Authorization همهٔ درخواست‌هافقط بدنهٔ POST /auth/refresh
وقتی تمام شدبا refresh_token یک جفت تازه بگیریدکاربر باید دوباره وارد شود

چرخه این است:

  1. کاربر وارد می‌شود و دو توکن می‌گیرد.
  2. اپ هر درخواست را با access_token می‌فرستد.
  3. یک ساعت بعد، سرور با 401 جواب می‌دهد.
  4. اپ با refresh_token یک جفت توکن تازه می‌گیرد و همان درخواست را دوباره می‌فرستد. کاربر چیزی نمی‌بیند.
  5. اگر رفرش هم رد شد، نشست واقعاً تمام شده و اپ کاربر را به صفحهٔ ورود می‌برد.

قدم ۱: ثبت‌نام و ورود

ثبت‌نام با ایمیل و رمز است. رمز دست‌کم ۸ کاراکتر است و تأیید ایمیل لازم نیست. مسیرهای auth کلید API نمی‌خواهند، پس اپ می‌تواند بدون هیچ کلیدی آن‌ها را صدا بزند:

curl -X POST https://api.fikaro.ir/my-app/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "sara@example.com", "password": "a-strong-password"}'
{
  "user": { "id": "0192f3a1-...", "email": "sara@example.com", "role": "user" },
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-10-08T13:00:00Z"
}

ورود همان شکل را دارد و جوابش 200 است:

curl -X POST https://api.fikaro.ir/my-app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "sara@example.com", "password": "a-strong-password"}'

جواب ورود یک فیلد اضافه هم دارد: must_change_password. اگر رمز کاربر را از پنل بازنشانی کرده باشید، این فیلد true است و اپ باید کاربر را اول به صفحهٔ تغییر رمز ببرد.

expires_at زمان انقضای access_token است، نه refresh_token. هر کاربر تازه نقش user می‌گیرد. اگر کاربری با کد پیامکی ساخته شده باشد، به‌جای email می‌توانید mobile بفرستید. ورود با کد پیامکی هم دقیقاً همین جفت توکن را برمی‌گرداند و از قدم ۲ به بعد هیچ فرقی ندارد. جزئیاتش در کلیدها و احراز هویت است.

خطاهایی که صفحهٔ ورود باید بشناسد:

وضعیتcodeیعنی
401invalid_credentialsایمیل/موبایل یا رمز نادرست است
409email_takenدر ثبت‌نام: این ایمیل قبلاً ثبت شده است
400validation_failedایمیل نامعتبر است یا رمز کمتر از ۸ کاراکتر است
429rate_limitedبعد از ۵ رمز اشتباه، ورود ۱۵ دقیقه قفل می‌شود
403email_auth_disabledورود با ایمیل در تنظیمات پروژه خاموش است

همهٔ خطاها application/problem+json هستند. روی code تصمیم بگیرید و detail را به کاربر نشان دهید؛ detail از قبل یک جملهٔ فارسی خواناست.

قدم ۲: هر دو توکن را امن نگه دارید

بعد از هر ورود و هر رفرش، هر دو توکن را ذخیره کنید. refresh_token سی روز اعتبار دارد و با آن می‌شود از طرف کاربر وارد شد، پس جای امن می‌خواهد:

  • اندروید: EncryptedSharedPreferences یا Keystore، نه SharedPreferences معمولی.
  • iOS: Keychain، نه UserDefaults.
  • Flutter: پکیج flutter_secure_storage.
  • وب: localStorage ساده است، ولی هر اسکریپتی در صفحه آن را می‌خواند. اگر سرور خودتان را دارید، کوکی httpOnly امن‌تر است.

توکن را در URL، لاگ یا گزارش خطا نگذارید.

قدم ۳: درخواست از طرف کاربر

access_token را در هدر Authorization بفرستید. از این لحظه سرور درخواست را با دسترسی همین کاربر اجرا می‌کند، و اگر برای جدولی «فقط رکوردهای خود کاربر» را تنظیم کرده باشید، کاربر فقط رکوردهای خودش را می‌بیند:

curl https://api.fikaro.ir/my-app/v1/order \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

در هر درخواست فقط یک اعتبار بفرستید: یا کلید API، یا توکن کاربر.

مشخصات کاربر واردشده را از GET /auth/me بگیرید. این مسیر فقط توکن کاربر قبول می‌کند و با کلید API جواب 401 auth_token_required می‌دهد. نام فیلدهای این جواب camelCase است:

curl https://api.fikaro.ir/my-app/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
{
  "id": "0192f3a1-...",
  "email": "sara@example.com",
  "role": "user",
  "lastLoginAt": "2026-10-08T12:00:00Z",
  "createdAt": "2026-10-01T09:30:00Z"
}

قدم ۴: بفهمید توکن تمام شده

یک ساعت بعد از ورود، هر درخواستی که access_token قدیمی را بفرستد این را می‌گیرد:

{
  "type": "https://fikaro.ir/errors/invalid_token",
  "status": 401,
  "detail": "توکن tenant نامعتبر یا منقضی است",
  "code": "invalid_token"
}

قاعدهٔ ساده و درست این است: اگر درخواستی که توکن کاربر داشت 401 گرفت، یک بار رفرش کنید و همان درخواست را یک بار دیگر بفرستید. اگر باز هم 401 آمد، دوباره رفرش نکنید؛ کاربر را به صفحهٔ ورود ببرید. یک بار تلاش دوباره کافی است و اپ هیچ‌وقت در حلقه نمی‌افتد.

اگر بخواهید قبل از خطا رفرش کنید، از expires_at استفاده کنید و حدود یک دقیقه زودتر رفرش کنید. ولی قاعدهٔ 401 را حتی در این حالت هم نگه دارید: ساعت گوشی ممکن است درست نباشد، و نشستی که با خروج باطل شده باشد هم 401 می‌گیرد.

قدم ۵: توکن را تازه کنید

refresh_token را در بدنه بفرستید. این درخواست هدر Authorization لازم ندارد:

curl -X POST https://api.fikaro.ir/my-app/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

جوابش همان شکل جواب ورود است: user و یک جفت توکن تازه. سه نکته که بیشتر پیاده‌سازی‌ها جا می‌اندازند:

  1. هر دو توکن را جایگزین کنید، نه فقط access_token. مهلت سی‌روزه از آخرین رفرش حساب می‌شود، پس اپی که refresh_token تازه را ذخیره کند، کاربرش را تا وقتی دست‌کم ماهی یک بار اپ را باز کند وارد نگه می‌دارد.
  2. در هر لحظه فقط یک رفرش. اگر سه درخواست هم‌زمان 401 بگیرند، فقط یکی رفرش کند و دوتای دیگر منتظر همان جواب بمانند. وگرنه سه رفرش موازی می‌رود و ممکن است جواب قدیمی‌تر روی توکن‌های تازه‌تر ذخیره شود.
  3. نام فیلد refresh_token با زیرخط است، نه refreshToken.

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

وقتی رفرش رد می‌شود

همهٔ رد شدن‌ها 401 هستند و code دلیل را می‌گوید:

codeعلتاپ چه کند
refresh_token_expiredسی روز از آخرین رفرش گذشته استصفحهٔ ورود
refresh_token_revokedکاربر خارج شده یا رمزش عوض شده است، روی همین دستگاه یا دستگاه دیگرصفحهٔ ورود
refresh_token_invalidتوکن ناقص است، مال پروژهٔ دیگری است، حساب کاربر حذف شده، یا به‌جای refresh_token، access_token فرستاده شده استصفحهٔ ورود؛ اگر access_token فرستاده‌اید، کدتان را درست کنید
refresh_token_missingفیلد refresh_token در بدنه نیامده استباگ کلاینت است: نام فیلد را درست کنید

در هر حالتی که به صفحهٔ ورود ختم می‌شود، اول هر دو توکن را از حافظهٔ دستگاه پاک کنید.

قدم ۶: خروج

curl -X POST https://api.fikaro.ir/my-app/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

جواب 204 است و دو چیز را باید بدانید:

  • خروج همهٔ نشست‌های کاربر را باطل می‌کند، روی همهٔ دستگاه‌ها. از این به بعد هیچ‌کدام از refresh_tokenهای او کار نمی‌کند.
  • access_tokenی که همین الان در دست اپ است ممکن است تا پایان همان یک ساعت هنوز پذیرفته شود. پس اپ باید بعد از خروج هر دو توکن را خودش هم پاک کند.

خروج با access_token انجام می‌شود. اگر آن توکن منقضی شده باشد، اول رفرش کنید و بعد خارج شوید؛ وگرنه خروج 401 می‌گیرد و refresh_token روی سرور تا سی روز معتبر می‌ماند. کدهای پایین همین کار را می‌کنند.

تغییر رمز و رمز فراموش‌شده

این دو هم نشست‌ها را عوض می‌کنند، پس بخشی از همین چرخه‌اند.

تغییر رمز. کاربر واردشده رمزش را با POST /auth/password عوض می‌کند:

curl -X POST https://api.fikaro.ir/my-app/v1/auth/password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"current_password": "old-password", "new_password": "new-password"}'

جوابش یک جفت توکن تازه است (access_token، refresh_token و expires_at). همان لحظه ذخیره‌شان کنید: تغییر رمز همهٔ نشست‌های قبلی، از جمله همانی که با آن درخواست را فرستادید، را باطل می‌کند. کاربری که با کد پیامکی ساخته شده و هنوز رمز ندارد، current_password را خالی می‌فرستد.

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

  1. اپ POST /auth/password/forgot را با {"email": "..."} صدا می‌زند. جواب همیشه 200 است، چه این ایمیل ثبت‌نام کرده باشد چه نه، تا کسی نتواند با این فرم بفهمد چه کسانی کاربر اپ شما هستند.
  2. کاربر ایمیلی می‌گیرد که به نشانی صفحهٔ شما با ?token=... می‌رود. این لینک ۳۰ دقیقه اعتبار دارد و فقط یک بار کار می‌کند.
  3. صفحهٔ شما POST /auth/password/reset را با {"token": "...", "new_password": "..."} صدا می‌زند. جوابش یک جفت توکن تازه است، پس کاربر همان‌جا وارد شده است.

اگر نشانی صفحهٔ بازیابی را وارد نکرده باشید، قدم اول با 400 و کد password_reset_not_configured برمی‌گردد.

رمز فراموش‌شده با موبایل. کاربری که شماره دارد، کدی را از POST /auth/otp/send می‌گیرد و بعد POST /auth/password/reset را با {"mobile": "...", "code": "...", "new_password": "..."} صدا می‌زند. جواب، مثل ورود، user و یک جفت توکن تازه است.

کد کامل کلاینت

همهٔ قدم‌های بالا در یک کلاس: ثبت‌نام، ورود، ذخیرهٔ امن توکن، رفرش خودکار بعد از 401 با فقط یک رفرش هم‌زمان، و خروجی که توکن را روی سرور هم باطل می‌کند. my-app را با اسلاگ پروژه‌تان عوض کنید.

// pubspec.yaml: http, flutter_secure_storage
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class AuthClient {
  static const _base = 'https://api.fikaro.ir/my-app/v1/auth';
  final _store = const FlutterSecureStorage();

  Future<void> signup(String email, String password) async {
    final r = await http.post(
      Uri.parse('$_base/signup'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'email': email, 'password': password}),
    );
    await _persist(r);
  }

  Future<void> login(String email, String password) async {
    final r = await http.post(
      Uri.parse('$_base/login'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'email': email, 'password': password}),
    );
    await _persist(r);
  }

  /// GET /me is the cheapest way to confirm a stored token is still good.
  Future<Map<String, dynamic>?> me() async {
    final r = await _authed((t) => http.get(
          Uri.parse('$_base/me'),
          headers: {'Authorization': 'Bearer $t'},
        ));
    return r.statusCode == 200 ? jsonDecode(r.body) : null;
  }

  Future<void> logout() async {
    await _authed((t) => http.post(
          Uri.parse('$_base/logout'),
          headers: {'Authorization': 'Bearer $t'},
        ));
    // The refresh token is dead server-side either way; drop both.
    await _store.deleteAll();
  }

  /// Runs [send] with the access token, and exactly once more if the server
  /// says the token expired. A second 401 means the session is genuinely over.
  Future<http.Response> _authed(
    Future<http.Response> Function(String token) send,
  ) async {
    var token = await _store.read(key: 'access') ?? '';
    var res = await send(token);
    if (res.statusCode != 401) return res;
    if (!await _refresh()) return res;
    token = await _store.read(key: 'access') ?? '';
    return send(token);
  }

  Future<bool> _refresh() async {
    final rt = await _store.read(key: 'refresh');
    if (rt == null) return false;
    final r = await http.post(
      Uri.parse('$_base/refresh'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode({'refresh_token': rt}),
    );
    if (r.statusCode != 200) {
      // Revoked by a logout or a password change elsewhere — sign in again.
      await _store.deleteAll();
      return false;
    }
    await _persist(r);
    return true;
  }

  Future<void> _persist(http.Response r) async {
    if (r.statusCode >= 400) {
      // Errors are problem+json: 'detail' is already a sentence in Persian.
      throw Exception(jsonDecode(r.body)['detail'] ?? 'خطای ناشناخته');
    }
    final b = jsonDecode(r.body);
    await _store.write(key: 'access', value: b['access_token']);
    await _store.write(key: 'refresh', value: b['refresh_token']);
  }
}

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

با کتابخانهٔ جاوااسکریپت

اگر اپ شما وب است، کتابخانهٔ @fikaro/client قدم‌های ۲ تا ۶ را خودش انجام می‌دهد: توکن‌ها را نگه می‌دارد، بعد از 401 یک بار رفرش می‌کند و درخواست را تکرار می‌کند، و در خروج حتی اگر شبکه قطع باشد حافظهٔ محلی را پاک می‌کند.

import { createClient, browserStorage } from "@fikaro/client";

const fikaro = createClient({
  project: "my-app",
  // بدون این، نشست فقط در حافظهٔ صفحه است و با تازه کردن صفحه از بین می‌رود
  storage: browserStorage(),
});

await fikaro.auth.login("sara@example.com", "a-strong-password");

// هر درخواست با توکن همین کاربر می‌رود؛ رفرش خودکار است
const { data } = await fikaro.from("order").list();

if (!fikaro.auth.isAuthenticated) {
  // نشست تمام شده است: صفحهٔ ورود
}

await fikaro.auth.logout();

همین مسیر را در این ویدیو روی یک صفحهٔ واقعی ببینید:

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

پیش از انتشار اپ

  • توکن‌ها در حافظهٔ امن دستگاه‌اند، نه در فایل یا تنظیمات ساده.
  • بعد از هر رفرش، هر دو توکن جایگزین می‌شوند.
  • در هر لحظه فقط یک رفرش در جریان است.
  • 401 دوم به صفحهٔ ورود می‌رود، نه به رفرش دوباره.
  • خروج هم روی سرور انجام می‌شود و هم توکن‌ها را از دستگاه پاک می‌کند.
  • کلید API کامل داخل اپ نیست. اپ برای خودش فقط کلید فقط‌خواندنی و توکن کاربر دارد.