احراز هویت و توکن‌ها

زربان سازمانی از جریان client_credentials استفاده می‌کند: کلید مخفی سازمان را با یک توکن کوتاه‌عمر تعویض می‌کنید و آن توکن را روی درخواست‌ها می‌فرستید. کلید مخفی خودش هرگز روی درخواست‌های عادی نمی‌رود.

دو چیزی که ممکن است غافلگیرتان کند

⚠

1. clientId شما همان شناسه سازمان است — رشته‌ای کوتاه و خوانا مانند PLN، نه یک UUID. اگر در داشبورد دنبال فیلد جداگانه‌ای به نام clientId می‌گردید، پیدایش نمی‌کنید؛ همان شناسه سازمان است.

2. grantType مقدار ClientCredentials است — با همین املا و همین حروف بزرگ، نه client_credentials که در بسیاری از سرویس‌های دیگر مرسوم است.

اعتبارنامه‌ها در داشبورد سازمانی، زیر کلیدهای API، نگهداری می‌شوند:

«شناسه کلاینت» همان شناسه سازمان است — در این نمونه PLN — و همان مقداری است که در clientId می‌فرستید. کلید مخفی پوشانده نمایش داده می‌شود؛ متن کامل آن فقط یک بار، در پاسخ چرخاندن کلید، برمی‌گردد.

گرفتن توکن

curl -sS -X POST "https://hd.zarban.io/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "PLN",
    "clientSecret": "sk_live_8f2c1a9b3e7d4f60a1c2b3d4e5f60718",
    "grantType": "ClientCredentials"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "refreshToken": "rt_3a1f9c2e7b8d4056a9c1e2f3b4d5e6f7",
  "expiresIn": 3600
}

فیلد	عمر	کارش چیست
accessToken	۱ ساعت (expiresIn بر حسب ثانیه)	روی هدر Authorization هر درخواست می‌رود.
refreshToken	۹۰ روز	برای گرفتن توکن دسترسی تازه، بدون فرستادن دوباره کلید مخفی.

استفاده از توکن

curl -sS "https://hd.zarban.io/accounts?entityId=PLN&limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

تازه کردن توکن

curl -sS -X POST "https://hd.zarban.io/oauth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_3a1f9c2e7b8d4056a9c1e2f3b4d5e6f7"
  }'

پاسخ دقیقاً همان ساختار /oauth/token است.

⚠

توکن تازه‌سازی می‌چرخد. هر بار که /oauth/refresh را صدا می‌زنید، refreshToken جدیدی می‌گیرید و قبلی دیگر کار نمی‌کند. اگر پاسخ را ذخیره نکنید، در تازه‌سازی بعدی با 401 روبه‌رو می‌شوید و باید از کلید مخفی دوباره شروع کنید. هر دو توکن را با هم ذخیره کنید، نه فقط accessToken را.

الگوی درست در سرویس شما

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

الگوی پیشنهادی:

1. توکن و زمان انقضایش را در حافظه یا کش مشترک نگه دارید.

2. پیش از هر درخواست، اگر کمتر از حدود ۵ دقیقه تا انقضا مانده بود، تازه‌اش کنید. این حاشیه نمی‌گذارد توکن درست وسط ارسال یک درخواست منقضی شود.

3. اگر با وجود این، پاسخ 401 گرفتید: یک بار تازه کنید و همان درخواست را دوباره بفرستید. اگر باز 401 شد، خطا را به لایه بالاتر بدهید — دوباره تلاش نکنید، چون احتمالاً کلید مخفی باطل شده است.

4. در سرویس چندنمونه‌ای، تازه‌سازی را قفل کنید یا توکن را در کش مشترک بگذارید؛ وگرنه هر نمونه جداگانه تازه می‌کند و چون توکن تازه‌سازی می‌چرخد، نمونه‌ها توکن یکدیگر را باطل می‌کنند.

نگهداری کلید مخفی

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

چرخاندن کلید

از داشبورد سازمانی، یا با POST /tenants/{id}/secret:

curl -sS -X POST "https://hd.zarban.io/tenants/PLN/secret" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

⚠

چرخاندن کلید فوری اعمال می‌شود و کلید قبلی را بلافاصله باطل می‌کند؛ کلید تازه هم فقط در همین پاسخ به‌صورت متن ساده برمی‌گردد. تا لحظه‌ای که کلید تازه روی همه نمونه‌های سرویس شما مستقر شود، فراخوانی /oauth/token با کلید قدیمی پاسخ 401 می‌گیرد. مسیر پیشنهادی این است که استقرار کلید تازه را آماده کنید و سپس چرخاندن را اجرا کنید.

دو نوع توکن

در توضیحات API به دو عبارت برمی‌خورید:

نوع	از کجا	برای چه
توکن سازمان (tenant / OAuth)	/oauth/token با کلید مخفی	سرویس به سرویس. همان چیزی که در این مستندات استفاده می‌شود.
توکن عضو (member)	/members/token با رایانامه و گذرواژه	افرادی که وارد داشبورد سازمانی می‌شوند.

برای یکپارچه‌سازی سرور خود همیشه از توکن سازمان استفاده کنید. تفاوت عملی مهم: در توکن سازمان، سازمان از خود توکن خوانده می‌شود، بنابراین پارامتر tenantId در فهرست‌ها لازم نیست و اگر بفرستید هم نادیده گرفته می‌شود.

⚠

اعتبارنامه سازمان (clientId و clientSecret) را برای اتصال سرور به سرور ساخته‌ایم. اعتبارنامه رایانامه و گذرواژه اما به یک کاربر انسانی تعلق دارد: دامنه دسترسی‌اش فرق می‌کند و اعتبارش به عضویت همان فرد در سازمان بند است.

خطاهای رایج

کد	یعنی چه	کار درست
401 روی /oauth/token	clientId یا clientSecret اشتباه است.	کلید را بررسی کنید. دوباره تلاش نکنید.
401 روی مسیر عادی	توکن منقضی یا نامعتبر است.	یک بار تازه کنید و همان درخواست را تکرار کنید.
401 روی /oauth/refresh	توکن تازه‌سازی منقضی شده یا چرخیده.	از کلید مخفی دوباره توکن بگیرید.
403	توکن معتبر است اما سازمان شما این دسترسی را ندارد.	دسترسی‌ها را ببینید.