پرش به مطلب اصلی

روش‌های احراز هویت

وب‌سرویس پایاوا دو خانواده روش احراز هویت دارد: کلید API برای اتصال ساده‌ی یک حساب، و توکن (Access Token همراه با Refresh Token) برای برنامه‌هایی که از طرف کاربران مختلف درخواست می‌فرستند. هر دو روش روی همه‌ی endpointهای این مستندات کار می‌کنند و فرق آن‌ها فقط در نحوه‌ی دریافت و ارسال اعتبارنامه است.

مقایسه​

معیارکلید APIتوکن با رفرش‌توکن و سشن
مناسب برایسرور شما به حساب خودتان وصل می‌شودنرم‌افزاری که چند مشتری دارد و هر مشتری حساب خودش را دارد
دریافت اعتبارنامهساخت در پنلورود با پیامک تأیید از طریق API
هدر درخواستX-Api-KeyAuthorization: Bearer
انقضاندارد، مگر در پنل منقضی یا غیرفعال شوددارد؛ باید نوسازی شود
هدرهای اضافهندارد (مگر کلاینت شما X-Client-App را الزامی کرده باشد)X-Client-App و X-Session-Key هنگام دریافت و نوسازی
محدودیت آی‌پیقابل تعریفندارد

کدام روش را انتخاب کنم؟​

  • اگر برنامه‌ی شما فقط به یک حساب پایاوا وصل می‌شود (مثلاً فروشگاه اینترنتی شما)، کلید API را انتخاب کنید.
  • اگر شما سازنده‌ی نرم‌افزاری مانند برنامه‌ی حسابداری هستید که هر مشتری آن حساب پایاوای خودش را به نرم‌افزار وصل می‌کند، از توکن و سشن و الگوی اتصال برنامه‌های چندمشتری استفاده کنید.

هدر X-Client-App​

برخی کلاینت‌ها برای ارسال پیامک باید هدر X-Client-App را هم بفرستند. اگر کلاینت شما چنین الزامی داشته باشد و هدر نباشد، پاسخ status برابر 4500 دارد؛ و اگر مقدار با کلاینت مطابقت نداشته باشد، 4501 برمی‌گردد. جزئیات در کدهای وضعیت و خطاها آمده است.

نکات امنیتی مشترک​

  • همیشه از HTTPS استفاده کنید.
  • کلید API، توکن‌ها و کلید X-Client-App را در مخزن کد یا فایل‌های عمومی قرار ندهید.
  • هر اعتبارنامه‌ی لورفته را فوراً لغو یا بازنشانی کنید.