کلیدهای API

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

ایجاد کلید API

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

عملیات‌ها

• ویرایش: نام، یادداشت، تنظیمات مجوزها، تاریخ انقضا یا وضعیت (فعال/غیرفعال) کلید را تغییر دهید.
• ابطال و صدور مجدد: کلید مخفی فعلی را بلافاصله ابطال کرده و یک کلید جدید با همان تنظیمات صادر کنید. در صورتی که کلید لو رفته باشد یا نیاز به چرخش (rotation) داشته باشد از این گزینه استفاده کنید.
• حذف: کلید API را برای همیشه حذف کنید. هر درخواستی که از این پس با این کلید ارسال شود بلافاصله خطای عدم دسترسی (unauthorized) دریافت می‌کند.
• حذف دسته‌جمعی: چند کلید API را انتخاب کرده و آن‌ها را به صورت یکجا حذف کنید تا اطلاعات اتصال‌های غیرفعال پاکسازی شوند.

توصیه‌های امنیتی

• اصل حداقل سطح دسترسی (Least Privilege): در صورت امکان، گزینه «ارث‌بری مجوزهای مدیر» را غیرفعال کرده و فقط مجوزهای دقیقی را که کلید API برای کار خود نیاز دارد مشخص کنید.
• تنظیم تاریخ انقضا: برای اتصال‌های موقت از تاریخ انقضا استفاده کنید تا در صورت لو رفتن اطلاعات، سوء استفاده در کمترین زمان ممکن متوقف شود.
• نظارت بر شناسه کلید: هر کلید API دارای یک شناسه کلید (Key ID) منحصربه‌فرد در جدول است. از این شناسه برای شناسایی کلید در لاگ‌های سرور بدون فاش شدن کلید مخفی اصلی استفاده کنید.
• غیرفعال کردن کلیدهای غیرفعال: اگر از یک کلید API در حال حاضر استفاده نمی‌شود، به جای حذف، وضعیت آن را به غیرفعال تغییر دهید تا در صورت نیاز در آینده بتوانید دوباره آن را فعال کنید.

استفاده از کلید API

شما می‌توانید برای احراز هویت درخواست‌های HTTP خود به REST API پنل، کلید ساخته شده را به یکی از دو روش زیر ارسال کنید:

۱. هدر HTTP اختصاصی (توصیه شده)

کلید را در هدر X-Api-Key درخواست HTTP خود قرار دهید:

curl -H "X-Api-Key: pg_key_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
     https://your-panel-domain/api/admin/users

۲. هدر Authorization

به عنوان روش جایگزین، می‌توانید از هدر استاندارد Authorization با پیشوند apikey استفاده کنید:

curl -H "Authorization: apikey pg_key_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
     https://your-panel-domain/api/admin/users