‏درس‌های Nango از نگه‌داری auth برای ۹۰۰ API

مهٔ ۲۰۲۵ تیم Nango یه PR مرج کرد که یه شرط if توش هیچ‌وقت اجرا نمی‌شد و در نتیجه توکن‌های تازه‌گرفته‌شده تو دیتابیس ذخیره نمی‌شدن. کمتر از دو ساعت طول کشید تا باگ پیدا و ریورت بشه، ولی تو همون دو ساعت جاب‌های زمان‌بندی‌شده برای صدها اتصال توکن گرفته و دورشون ریخته بودن. Nango یه پروژهٔ متن‌بازه که اتصال اپلیکیشن‌ها به APIهای شخص ثالث رو مدیریت می‌کنه، پس این اتصال‌ها مال کاربرهای مشتری‌های اون‌ها بود.

اینجا بود که فهمیدن چند تا ارائه‌دهنده refresh token رو rotate می‌کنن؛ یعنی لحظه‌ای که توکن جایگزین صادر می‌شه، توکن قبلی باطله. Airtable و Atlassian همین‌طورن، Salesforce و Slack هم اگه rotation روی اپ OAuth روشن باشه. برای بقیهٔ سرویس‌ها توکن قدیمی هنوز کار می‌کرد و رفرش بعدی خودش اتصال رو درست کرد، ولی برای این دسته راه برگشتی نبود و مشتری‌ها مجبور شدن از کاربرهاشون بخوان دوباره صفحهٔ رضایت رو رد کنن.

درس اولی که نویسنده می‌گیره اینه که refresh token رو باید مثل پول دید نه مثل کش: توکن جدید قبل از هر کار دیگه‌ای persist می‌شه، این مسیر تست رگرسیون مخصوص خودش رو داره، و هر ناهنجاری تو رفرش مستقیم تیم on-call رو پیج می‌کنه. رفتار ارائه‌دهنده‌ها هم یکسان نیست: Airtable با یه رفرش تکراری بعد از مهلت کوتاهش کل authorization اپ رو باطل می‌کنه، ولی Xero تا ۳۰ دقیقه اجازهٔ retry با توکن قبلی رو می‌ده.

درس دوم اینه که نمی‌شه مطمئن بود access token کِی منقضی می‌شه. تو RFC 6749 فیلد expires_in اختیاریه. Zendesk فقط وقتی این فیلد رو برمی‌گردونه که صریحاً درخواستش کنی، در حالی که توکن به‌هرحال طبق سیاست پیش‌فرض منقضی می‌شه. پاسخ Salesforce اصلاً انقضا نداره و باید از اندپوینت introspection پرسید. طول عمر refresh token هم فرق می‌کنه: NetSuite بعد از ۷ روز، ولی Google عملاً بی‌نهایت مگر تو شرایط مستند مثل شش ماه بی‌استفاده موندن.

بدتر از همه اینه که شکست auth همیشه شبیه شکست نیست. اندپوینت توکن Zoho CRM کد ۲۰۰ برمی‌گردونه و خطا رو تو بدنه می‌ذاره، Workday و Dayforce وقتی یه policy دسترسی نباشه فقط دادهٔ خالی می‌دن، و بررسی اعتبار LastPass تو کد Nango واقعاً دنبال رشتهٔ Authorization Error تو متن پاسخ می‌گرده. برای همین ۲۷۶ تا از حدود ۹۳۵ ارائه‌دهندهٔ رجیستری‌شون یه اندپوینت احرازشده معرفی می‌کنن تا سلامت credential تست بشه.

نویسنده در پایان ده درخواست از سازندهٔ API داره که مهم‌ترین‌هاش اینه: همیشه expires_in رو برگردونین، اگه refresh token رو rotate می‌کنین یه مهلت کوتاه مثل ۳۰ دقیقهٔ Xero بذارین، خطای دقیق‌تر از invalid_grant بدین، تغییر auth رو مثل تغییر breaking نسخه‌بندی و اعلام کنین، و کد ۲۰۰ رو فقط به معنی موفقیت به کار ببرین. ۱۶ درصد کامیت‌های کانفیگ ارائه‌دهنده‌های Nango هم فقط رفع همین ناسازگاری‌هاست.

نکات کلیدی:

• یه باگ دو ساعته در مهٔ ۲۰۲۵ باعث شد توکن صدها اتصال بازیابی‌ناپذیر بشه و کاربرها دوباره consent بدن.

• Airtable و Atlassian refresh token قبلی رو فوری باطل می‌کنن؛ Xero تا ۳۰ دقیقه مهلت retry می‌ده.

• در RFC 6749 فیلد expires_in اختیاریه؛ Salesforce انقضا نمی‌ده و باید introspection صدا زد.

• refresh token در NetSuite بعد از ۷ روز منقضی می‌شه، مال گوگل عملاً دائمیه مگر در شرایط مستند.

• ۲۷۶ تا از حدود ۹۳۵ ارائه‌دهندهٔ رجیستری Nango یه اندپوینت احرازشده برای چک‌کردن credential دارن.

• ۱۶ درصد کامیت‌های کانفیگ ارائه‌دهنده‌ها صرفاً رفع تغییرات ناگهانی سمت خود ارائه‌دهنده‌ست.