توکن‌های API

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

توکن چطور محدود می‌شود

توکن از سه راه محدود می‌شود، و هر کدام در هر درخواست دوباره بررسی می‌شود:

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

تغییر هر کدام از این‌ها در درخواست بعدی توکن اعمال می‌شود.

ساختن توکن

1. افزودن.
2. توضیحات: توکن برای چیست، تا بعداً بشناسیدش.
3. به‌جای: ادمینی که توکن دسترسی او را می‌گیرد.
4. نقش: سطح، حداکثر تا سطح آن ادمین.
5. اسکوپ‌ها: برای همه‌ی مسیرهایی که نقش به آن‌ها می‌رسد (از جمله اسکوپ‌هایی که نسخه‌های بعدی اضافه می‌کنند) بدون محدودیت را بگذارید، یا تیکش را بردارید و انتخاب کنید.
6. شناسهٔ افزونه: برای یکپارچه‌سازی معمولی خالی‌اش بگذارید. برای توکنی است که متعلق به افزونه‌ای است که دستی اضافه می‌کنید (ببینید صفحه‌ی افزونه‌ها).
7. درخواست در دقیقه: 0 از پیش‌فرض پنل، یعنی ۱۲۰، استفاده می‌کند.
8. اعتبار (روز): 0 یعنی هیچ‌وقت منقضی نمی‌شود.
9. ذخیره.

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

TIP

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

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

curl -H "Authorization: Bearer $NEXORA_TOKEN" \
  https://panel.example.com/your-base-path/api/v1/me

/api/v1/me پاسخ می‌دهد توکن به‌جای کدام ادمین عمل می‌کند و چه اسکوپ‌هایی دارد.

اسکوپ‌ها

هر اسکوپ :write اسکوپ :read متناظرش را هم دارد. فرم پنل نام‌های ستون دوم را نشان می‌دهد؛ API و مستندات API از ستون اول استفاده می‌کنند.

اسکوپ	نمایش به شکل
users:read	دیدن کاربران
users:write	ساخت و ویرایش کاربران
nodes:read	دیدن نودها
nodes:write	پیکربندی نودها
tunnels:read	دیدن تونل‌ها
tunnels:write	پیکربندی تونل‌ها
nodes:install	نصب نود از طریق SSH
templates:read	دیدن تمپلیت‌ها
templates:write	ویرایش تمپلیت‌ها
pool:read	دیدن ورودی‌ها، خروجی‌ها و rule setها
pool:write	ویرایش ورودی‌ها، خروجی‌ها و rule setها
certificates:read	دیدن گواهی‌ها
certificates:write	صدور و ویرایش گواهی‌ها
settings:read	دیدن تنظیمات
settings:write	تغییر تنظیمات
stats:read	ترافیک، گزارش‌ها و سلامت
tools:write	تولید کلید
admins:write	مدیریت اپراتورها و نقش‌ها
tokens:write	مدیریت توکن‌های API
license:write	مدیریت لایسنس
backup:read	دانلود پشتیبان
backup:write	گرفتن و حذف پشتیبان
backup:deliver	فرستادن فایل به چت بکاپ
security:read	دیدن فهرست مسدودها
security:write	تغییر فهرست مسدودها
webhooks:read	دیدن مشترکان رویداد
webhooks:write	تغییر مشترکان رویداد
services:read	دیدن سرویس‌های پنل
services:write	تنظیم و آزمایش سرویس‌های پنل

کمترین چیزی را بدهید که برنامه لازم دارد. سه اسکوپ مدیریت خود پنل‌اند: admins:write، tokens:write و license:write. مگر اینکه برنامه واقعاً لازمشان داشته باشد آن‌ها را ندهید؛ توکنی که آن‌ها را ندارد نمی‌تواند حساب بسازد یا توکن دیگری صادر کند، پس توکن لورفته نمی‌تواند خودش را ماندگار کند. backup:read کل دیتابیس را با همه‌ی اطلاعات ورودش بیرون می‌خواند، و nodes:install با کاربر root وارد سرورهایتان می‌شود، پس هر دو همان‌قدر احتیاط می‌خواهند.

چند مسیر به روی هر توکنی، با هر اسکوپی، بسته‌اند: تغییر گذرواژه‌ی خود درخواست‌دهنده، چیدمان داشبوردش، ری‌استارت پنل، به‌روزرسانی پنل و بازیابی پشتیبان. چند مسیر به روی هر توکنی باز است: /api/v1/me، فهرست اسکوپ‌ها و فهرست رویدادها.

سقف نرخ درخواست

هر توکن سهمیه‌ای از درخواست در دقیقه دارد (۱۲۰، مگر عدد دیگری تنظیم کنید). هر پاسخ X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را دارد. درخواستی که از سهمیه فراتر برود 429 همراه Retry-After می‌گیرد؛ پیش از درخواست بعدی همان چند ثانیه صبر کنید.

فهرست

ستون
توضیحات	با برچسب افزونه: name وقتی توکن در اختیار یک افزونه است
به‌جای	ادمینی که توکن به آن وابسته است
نقش	سطحش
اسکوپ‌ها	بدون محدودیت، یا تعداد اسکوپ‌ها (نشانگر را رویش ببرید تا فهرستشان را ببینید)
آخرین استفاده	آخرین باری که استفاده شده؛ نشانگر را رویش ببرید تا آدرسی را که از آن آمده ببینید
انقضا	تاریخ انقضایش، یا هرگز

توکن پس از ساخته شدن ویرایش نمی‌شود: حذفش کنید و یکی دیگر بسازید. توکنی که در اختیار یک افزونه است اینجا قابل حذف نیست؛ همراه افزونه در صفحه‌ی صفحه‌ی افزونه‌ها تغییر می‌کند یا برداشته می‌شود.

API

مستندات API در بالای این صفحه مستندات همین نصب را باز می‌کند، با آدرس‌های خودش: همه‌ی مسیرها، اسکوپی که هر کدام لازم دارد، فهرست‌گیری و صفحه‌بندی، تلاش دوباره با Idempotency-Key، و کدهای وضعیت. همین مطالب در مرجع API هم هست.

بر پایه‌ی پیشوند /api/v1 بسازید. این قرارداد عمومی پایدار است. پیشوند بی‌نسخه‌ی /api مال خود رابط پنل است و ممکن است همراه آن تغییر کند.

مرتبط

• ادمین‌ها و نقش‌ها: ادمین توکن چه کاری می‌تواند بکند.
• وب‌هوک‌ها و رویدادها: به‌جای پرس‌وجوی پیاپی، رویدادها را دریافت کنید.
• مرجع API: مستندات API.
• گزارش تغییرات: یک توکن چه چیزی را تغییر داده.