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

احراز هویت با کلید API

کلید API یک رشته‌ی ثابت است که در پنل می‌سازید و در هر درخواست می‌فرستید. این روش نیازی به ورود، توکن و نوسازی ندارد. کلیدها با پیشوند pyk_sms_ شروع می‌شوند. روش ساخت کلید در کلید API در پنل توضیح داده شده است.

ارسال کلید​

سامانه کلید را به یکی از سه روش زیر می‌پذیرد. روش اول توصیه می‌شود:

روشنمونه
هدر اختصاصی (توصیه‌شده)X-Api-Key: YOUR_API_KEY
هدر Authorization با طرح ApiKeyAuthorization: ApiKey YOUR_API_KEY
هدر Authorization با طرح BearerAuthorization: Bearer YOUR_API_KEY

در روش سوم، مقدار فقط وقتی به‌عنوان کلید API شناخته می‌شود که با پیشوند pyk_sms_ شروع شود؛ در غیر این صورت به‌عنوان توکن JWT تفسیر می‌گردد. این رفتار باعث می‌شود یک کلاینت بتواند هر دو نوع اعتبارنامه را با همان هدر Authorization بفرستد.

نمونه‌ی درخواست​

نمونه‌ی زیر موجودی حساب را با کلید API دریافت می‌کند:

curl -X GET "https://api.payavasms.com/sms/api/Balance" \
-H "X-Api-Key: YOUR_API_KEY"

قواعد اعتبارسنجی​

درخواست در این شرایط رد می‌شود:

  • کلید ارسال نشده باشد.
  • ساختار کلید معتبر نباشد (پیشوند نادرست یا طول کمتر از حد مجاز).
  • کلید در سامانه ثبت نشده یا غیرفعال شده باشد.
  • کلید منقضی شده باشد.
  • فهرست آی‌پی مجاز تعریف شده باشد و آدرس فرستنده در آن نباشد.

پاسخ خطا​

خطاهای احراز هویت با کد وضعیت HTTP و بدنه‌ی JSON برگردانده می‌شوند:

کد HTTPمقدار errorمعنا
401missing_api_keyهیچ کلیدی ارسال نشده است
401invalid_api_keyکلید نامعتبر، غیرفعال، منقضی یا از آی‌پی غیرمجاز است
403insufficient_scopeکلید به این سرویس دسترسی ندارد
{
"error": "invalid_api_key",
"error_description": "ApiKey وارد شده معتبر نمی باشد"
}
نکته

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