توکن‌های API

توکن دسترسی شخصی بسازید تا اسکریپت‌ها، پایپ‌لاین‌های CI و ابزارهای دیگر بتوانند از طرف شما از REST API پنل استفاده کنند.

مسیر

توکن‌های API (/api-tokens)، زیر حساب من.

در این صفحه چه چیزی هست

جدولی از توکن‌های شما:

• نام — برچسبی که به توکن داده‌اید.
• دسترسی‌ها — کارهایی که توکن اجازهٔ انجامشان را دارد، مثلاً dns:read یا cache:purge.
• آی‌پی‌های مجاز — آدرس‌هایی که توکن از آن‌ها کار می‌کند. هر آدرسی یعنی بدون محدودیت.
• آخرین استفاده — آخرین زمان استفاده از توکن و آدرس IP آن.
• انقضا — هر توکن تاریخ انقضا دارد. توکن منقضی‌شده دیگر کار نمی‌کند.
• دامنه‌ها — دامنه‌هایی از حساب شما که توکن به آن‌ها دسترسی دارد. همهٔ دامنه‌ها یعنی تمام دامنه‌های حساب.

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

ساخت توکن

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

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

توکن را در هدر Authorization بفرستید:

curl -H "Authorization: Bearer <token>" https://<panel address>/api/v1/user/me

ابطال توکن

در ردیف توکن روی ابطال کلیک و تأیید کنید. هر ابزاری که از این توکن استفاده می‌کند بلافاصله از کار می‌افتد. یک اسکریپت هم می‌تواند با DELETE /api/v1/user/tokens/current توکن خودش را باطل کند.

نکته‌ها

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

رفع اشکال

• 401 Unauthenticated — توکن اشتباه، باطل‌شده یا منقضی است. ستون انقضا را بررسی کنید.
• 403 Invalid ability provided — توکن دسترسی لازم برای آن endpoint را ندارد. مستندات API دسترسی لازم هر endpoint را نشان می‌دهد.
• 403 This token cannot be used from your IP address — درخواست از آدرسی خارج از آی‌پی‌های مجاز توکن آمده است.
• خطای 404 برای یکی از دامنه‌هایتان — توکن به دامنه‌های دیگری محدود شده است. ستون دامنه‌ها را بررسی کنید.
• 429 Too Many Requests — به سقف تعداد درخواست رسیده‌اید. به اندازهٔ ثانیه‌های هدر Retry-After صبر کنید.