روشهای احراز هویت
وبسرویس پایاوا دو خانواده روش احراز هویت دارد: کلید API برای اتصال سادهی یک حساب، و توکن (Access Token همراه با Refresh Token) برای برنامههایی که از طرف کاربران مختلف درخواست میفرستند. هر دو روش روی همهی endpointهای این مستندات کار میکنند و فرق آنها فقط در نحوهی دریافت و ارسال اعتبارنامه است.
مقایسه
| معیار | کلید API | توکن با رفرشتوکن و سشن |
|---|---|---|
| مناسب برای | سرور شما به حساب خودتان وصل میشود | نرمافزاری که چند مشتری دارد و هر مشتری حساب خودش را دارد |
| دریافت اعتبارنامه | ساخت در پنل | ورود با پیامک تأیید از طریق API |
| هدر درخواست | X-Api-Key | Authorization: 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را در مخزن کد یا فایلهای عمومی قرار ندهید. - هر اعتبارنامهی لورفته را فوراً لغو یا بازنشانی کنید.