توکن‌های API

توکن API کلیدی است که به یک اسکریپت اجازه می‌دهد مانند یک حساب پنل عمل کند. آن را در تنظیمات → API می‌سازید، محدودهٔ دسترسی‌اش را انتخاب می‌کنید و با هر درخواست می‌فرستید. این صفحه ساخت توکن، انتخاب دسترسی، انقضا و آدرس‌های مجاز، لغو توکن و خود مسیرهای توکن را توضیح می‌دهد.

ساخت توکن

1. تنظیمات → API را باز کنید.
2. ایجاد توکن API را بزنید.
3. یک نام بگذارید. نام بین ۱ تا ۶۴ نویسه است و برای همان حساب یکتا است.
4. دسترسی کامل را انتخاب کنید، یا خاموشش کنید و زیر دسترسی‌ها موارد دلخواه را تیک بزنید.
5. انقضا را انتخاب کنید: هرگز، ۳۰ روز، ۹۰ روز یا ۱ سال.
6. در صورت نیاز آی‌پی‌های مجاز را وارد کنید؛ در هر خط یک آدرس یا محدودهٔ CIDR.
7. رمز عبور فعلی را بزنید. اگر ورود دومرحله‌ای روشن است، کد ۲FA را هم وارد کنید.
8. ایجاد توکن API را بزنید.

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

هر حساب می‌تواند ۲۵ توکن داشته باشد. نام توکن برای همان حساب یکتاست، نه برای کل پنل.

کامل یا سفارشی

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

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

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

دسترسی‌ها

کلیدهای دسترسی همان کلیدهای ویرایشگر نقش‌ها هستند. صفر کردن مصرف و قطع اتصال دسترسی جدا از ویرایش دارند.

کلید	چه کاری اجازه می‌دهد
clients.view	فهرست و جست‌وجوی کاربران، خواندن یک کاربر، خواندن مصرف، دانلود پروفایل و کد QR.
clients.create	ساخت یک کاربر یا چند کاربر از یک طرح.
clients.edit	تغییر کاربر، روشن یا خاموش کردن، تمدید، تعویض گواهی، تعویض لینک اشتراک و همین کارها به‌صورت گروهی.
clients.delete	حذف یک کاربر یا چند کاربر.
clients.reset	صفر کردن مصرف یک کاربر یا چند کاربر.
clients.kick	بستن اتصال‌های باز یک کاربر یا چند کاربر.
connections.view	دیدن اتصال‌های زنده و تاریخچهٔ اتصال‌ها.
connections.kick	بستن یک اتصال باز.
groups.view	فهرست گروه‌ها. برای نماینده فقط گروه‌هایی که به او داده شده.
groups.manage	ساخت و تغییر گروه‌ها، کارهای گروهی و افزودن یا حذف گروه کاربران.
inbounds.view	own: فهرست کوتاه اینباندهای مجاز. all: فهرست کامل، جزئیات، استقرارها و گزارش‌ها.
inbounds.manage	ساخت و تغییر اینباندها، استقرار آن‌ها، تخصیص به نود و روشن یا خاموش کردن.
nodes.view	فهرست نودها، خواندن فرمان نصب و آمار میزبان.
nodes.manage	هم‌گام کردن نود و صفر کردن شمارنده‌های ترافیک آن.

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

انقضا

هرگز یعنی توکن تا وقتی لغو شود کار می‌کند. در غیر این صورت در زمان انتخاب‌شده از کار می‌افتد و 401 با token_expired می‌دهد.

انقضا از زمان ساخت حساب می‌شود. توکن تمدید نمی‌شود؛ توکن تازه بسازید و قدیمی را لغو کنید.

آی‌پی‌های مجاز

آی‌پی‌های مجاز تعیین می‌کند توکن از کجا استفاده شود. یک آدرس IPv4 یا IPv6 یا محدودهٔ CIDR اضافه کنید. فهرست تا ۳۲ مورد را می‌پذیرد. فهرست خالی هر آدرسی را اجازه می‌دهد.

درخواست از آدرس دیگر 403 با token_ip و آدرس در params.ip می‌گیرد. آدرس عمومی میزبان یا شبکهٔ ربات را اینجا بگذارید. اگر پنل پشت پراکسی است، پنل باید به آدرس forwarded همان پراکسی اعتماد کند تا این بررسی آدرس واقعی را ببیند.

لغو توکن

در تنظیمات → API توکن را پیدا کنید و لغو را بزنید. همان لحظه از کار می‌افتد. اسکریپتی که از آن استفاده می‌کند 401 با token_invalid می‌گیرد.

لغو برگشت ندارد. توکن تازه بسازید و اسکریپت را به‌روز کنید.

لغو توکن نماینده

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

نماینده توکن‌های خودش را در تنظیمات → API لغو می‌کند. صفحهٔ تنظیمات او فقط حساب من و API را نشان می‌دهد.

مسیرهای توکن

این مسیرها توکن‌ها را مدیریت می‌کنند. مخصوص نشست‌اند: به درخواست توکن token_forbidden می‌دهند، پس با نشست مرورگر صدا بزنید. مرورگر برای نوشتن هدر CSRF هم لازم دارد.

GET/api/account/tokensدسترسیanyفقط نشست

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

curl -sS -b cookies.txt "$BASE/account/tokens"

[
  {
    "id": 4,
    "name": "shop-bot",
    "prefix": "ovk_7f3c9a",
    "full": false,
    "perms": { "clients.view": "own", "clients.create": "own", "clients.edit": "own", "clients.reset": "own" },
    "allowIps": ["203.0.113.0/24"],
    "createdAt": 1793500000,
    "expiresAt": 1796000000,
    "lastUsedAt": 1793512345,
    "lastUsedIp": "203.0.113.9"
  }
]

POST/api/account/tokensدسترسیanyفقط نشست

توکن می‌سازد.

فیلد	نوع	لازم	معنی
name	string	بله	۱ تا ۶۴ نویسه، یکتا برای حساب.
full	boolean	خیر	همهٔ دسترسی‌های حساب را به توکن بده. وقتی روشن است perms نادیده گرفته می‌شود.
perms	object	برای توکن سفارشی	کلید دسترسی به محدوده: none، own یا all. توکن سفارشی حداقل یکی لازم دارد.
allowIps	string[]	خیر	تا ۳۲ آدرس یا شبکه. خالی یعنی هر آدرس.
expiresInDays	integer	خیر	0 برای هرگز، وگرنه ۱ تا ۳۶۵۰.
password	string	بله	رمز فعلی حساب.
code	string	وقتی ۲FA روشن است	کد فعلی برنامهٔ احراز هویت.

curl -sS -b cookies.txt -X POST "$BASE/account/tokens" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{
    "name": "shop-bot",
    "full": false,
    "perms": {
      "clients.view": "own",
      "clients.create": "own",
      "clients.edit": "own",
      "clients.reset": "own"
    },
    "allowIps": ["203.0.113.0/24"],
    "expiresInDays": 90,
    "password": "your-password"
  }'

{
  "token": "ovk_7f3c9a...",
  "item": {
    "id": 4,
    "name": "shop-bot",
    "prefix": "ovk_7f3c9a",
    "full": false,
    "perms": { "clients.view": "own", "clients.create": "own", "clients.edit": "own", "clients.reset": "own" },
    "allowIps": ["203.0.113.0/24"],
    "createdAt": 1793500000,
    "expiresAt": 1796000000,
    "lastUsedAt": 0,
    "lastUsedIp": ""
  }
}

خطاها: 400 با field: name، perms، allowIps یا expiresInDays؛ 400 با code: token_limit در ۲۵ توکن؛ 409 با field: name برای نام تکراری؛ 429 بعد از رمز یا کد اشتباه زیاد.

DELETE/api/account/tokens/{id}دسترسیanyفقط نشست

یکی از توکن‌های خودتان را لغو می‌کند. پارامتر مسیر id شناسهٔ توکن از فهرست است. توکن حساب دیگر 404 می‌دهد.

curl -sS -b cookies.txt -X DELETE \
  -H "X-CSRF-Token: $CSRF" \
  "$BASE/account/tokens/4"

{ "ok": true }

GET/api/admins/{id}/tokensدسترسیownerفقط نشست

فقط مالک. توکن‌های یک حساب را فهرست می‌کند. پارامتر مسیر id شناسهٔ حساب است. کلیدها برگردانده نمی‌شوند.

DELETE/api/admins/{id}/tokens/{tid}دسترسیownerفقط نشست

فقط مالک. یک توکن از یک حساب را لغو می‌کند. id شناسهٔ حساب و tid شناسهٔ توکن است.

صفحه‌های مرتبط

• نقش‌ها و نماینده‌های فروش: همان کلیدهای دسترسی با واژه‌های پنل.
• حساب‌های پنل: ساخت حساب و بخش توکن آن.
• نمای کلی API: آدرس پایه، خطاها و کارهایی که توکن نمی‌تواند بکند.
• شروع سریع: اولین درخواست با توکن.