احراز هویت REST API

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

هر درخواست REST API باید یک کلید محرمانه پروژه را با روش Bearer Authentication ارسال کند. کلید، پروژه و مجوزهای قابل‌استفاده را مشخص می‌کند؛ بنابراین شناسه پروژه جداگانه‌ای در body درخواست ارسال نمی‌شود.

هدرهای لازم

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

Authorization: Bearer YOUR_SECRET_API_KEY
Accept: application/json
Content-Type: application/json

برای endpointهای پیشنهاد، این هدر نیز الزامی است:

X-InAppify-App-ID: YOUR_APP_IDENTIFIER

X-InAppify-App-ID باید شناسه اپلیکیشنی باشد که داخل همان پروژه کلید API قرار دارد.

نمونه درخواست cURL

curl --request GET \
  --url "https://api.example.com/api/v1/subscribers/customer_123" \
  --header "Authorization: Bearer YOUR_SECRET_API_KEY" \
  --header "Accept: application/json"

نمونه درخواست PHP با cURL

<?php

$apiKey = getenv('INAPPIFY_SECRET_API_KEY');
$url = 'https://api.example.com/api/v1/subscribers/customer_123';

$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.$apiKey,
        'Accept: application/json',
    ],
]);

$body = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

$response = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

مجوزهای کلید

برای هر integration فقط مجوزهای موردنیاز را فعال کنید. مجوزهای REST API مستقل هستند؛ برای مثال کلیدی با customers:read اجازه حذف مشتری یا ویرایش ویژگی‌های او را ندارد.

مجوزکاربرد
customers:readدریافت یا ایجاد مشتری
customers:deleteحذف مشتری
customers:attributes:writeهمگام‌سازی ویژگی‌های مشتری
offerings:readدریافت پیشنهادهای یک اپلیکیشن
offerings:override:writeثبت پیشنهاد اختصاصی مشتری
offerings:override:deleteحذف پیشنهاد اختصاصی
entitlements:promotional:grantاعطای دسترسی تبلیغاتی
entitlements:promotional:revokeلغو دسترسی‌های تبلیغاتی
discount:generateساخت کد تخفیف اختصاصی

خطاهای احراز هویت

کلید ارسال نشده یا معتبر نیست (401):

{
  "status": false,
  "message": "API key is required."
}

کلید معتبر است ولی مجوز endpoint را ندارد (403):

{
  "status": false,
  "code": "API_KEY_ABILITY_DENIED",
  "message": "The API key does not have the required ability."
}