احراز هویت با کلید API
کلید API یک رشتهی ثابت است که در پنل میسازید و در هر درخواست میفرستید. این روش نیازی به ورود، توکن و نوسازی ندارد. کلیدها با پیشوند pyk_sms_ شروع میشوند. روش ساخت کلید در کلید API در پنل توضیح داده شده است.
ارسال کلید
سامانه کلید را به یکی از سه روش زیر میپذیرد. روش اول توصیه میشود:
| روش | نمونه |
|---|---|
| هدر اختصاصی (توصیهشده) | X-Api-Key: YOUR_API_KEY |
هدر Authorization با طرح ApiKey | Authorization: ApiKey YOUR_API_KEY |
هدر Authorization با طرح Bearer | Authorization: Bearer YOUR_API_KEY |
در روش سوم، مقدار فقط وقتی بهعنوان کلید API شناخته میشود که با پیشوند pyk_sms_ شروع شود؛ در غیر این صورت بهعنوان توکن JWT تفسیر میگردد. این رفتار باعث میشود یک کلاینت بتواند هر دو نوع اعتبارنامه را با همان هدر Authorization بفرستد.
نمونهی درخواست
نمونهی زیر موجودی حساب را با کلید API دریافت میکند:
- curl
- C#
- Python
- Node.js
- PHP
- Go
curl -X GET "https://api.payavasms.com/sms/api/Balance" \
-H "X-Api-Key: YOUR_API_KEY"
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://api.payavasms.com/sms/api/Balance");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
import requests
url = "https://api.payavasms.com/sms/api/Balance"
headers = {
"X-Api-Key": "YOUR_API_KEY",
}
response = requests.get(url, headers=headers)
print(response.status_code, response.text)
const response = await fetch("https://api.payavasms.com/sms/api/Balance", {
method: "GET",
headers: {
"X-Api-Key": "YOUR_API_KEY",
},
});
console.log(response.status, await response.text());
<?php
$ch = curl_init("https://api.payavasms.com/sms/api/Balance");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-Api-Key: YOUR_API_KEY",
],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . " " . $response;
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.payavasms.com/sms/api/Balance", nil)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
data, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode, string(data))
}
قواعد اعتبارسنجی
درخواست در این شرایط رد میشود:
- کلید ارسال نشده باشد.
- ساختار کلید معتبر نباشد (پیشوند نادرست یا طول کمتر از حد مجاز).
- کلید در سامانه ثبت نشده یا غیرفعال شده باشد.
- کلید منقضی شده باشد.
- فهرست آیپی مجاز تعریف شده باشد و آدرس فرستنده در آن نباشد.
پاسخ خطا
خطاهای احراز هویت با کد وضعیت HTTP و بدنهی JSON برگردانده میشوند:
| کد HTTP | مقدار error | معنا |
|---|---|---|
401 | missing_api_key | هیچ کلیدی ارسال نشده است |
401 | invalid_api_key | کلید نامعتبر، غیرفعال، منقضی یا از آیپی غیرمجاز است |
403 | insufficient_scope | کلید به این سرویس دسترسی ندارد |
{
"error": "invalid_api_key",
"error_description": "ApiKey وارد شده معتبر نمی باشد"
}
اگر درخواستها را پشت پراکسی یا شبکهی داخلی میفرستید، آدرسی که سرور میبیند همان آدرس خروجی شبکهی شماست. آیپی مجاز را بر اساس آن تعریف کنید.