احراز هویت API سرویکس با API Key

همه مسیرهای /api/v1/assets با کلید API حساب شما محافظت می شوند. سرویکس دو قالب هدر را می پذیرد. یکی را انتخاب کنید و در بک اند، worker، ربات یا ابزار خود به صورت ثابت استفاده کنید.

روش پیشنهادی: هدر X-API-Key

curl -sS https://servix.cc/api/v1/assets/USD_RLS \
  -H "X-API-Key: pk_live_your_key_here"

این روش برای Postman، curl و بیشتر کتابخانه های HTTP روشن و کم خطا است. در مجموعه Postman سرویکس نیز همین هدر از متغیر apiKey ساخته می شود.

روش جایگزین: طرح ApiKey در Authorization

curl -sS https://servix.cc/api/v1/assets/USD_RLS \
  -H "Authorization: ApiKey pk_live_your_key_here"

بین واژه ApiKey و مقدار کلید یک فاصله لازم است. این قالب با Bearer متفاوت است؛ توکن Bearer حساب وب جای کلید API مشتری را نمی گیرد.

ترکیب های رد شده

• ارسال کلید در query string مانند api_key یا key پشتیبانی نمی شود؛
• اگر X-API-Key و Authorization: ApiKey مقدار متفاوت داشته باشند، پاسخ 401 است؛
• اگر هم زمان X-API-Key و Authorization: Bearer ارسال شوند، درخواست برای جلوگیری از ابهام رد می شود؛
• کلید لغو شده، ناشناخته یا مربوط به حساب بدون دسترسی فعال معتبر نیست.

کلید را کجا بسازم؟

بعد از فعال شدن حساب تست یا اشتراک، به Profile > API Keys بروید. کلید تازه را بسازید و مقدار کامل آن را همان لحظه در secret manager، متغیر محیطی سرور یا تنظیمات محرمانه پلتفرم خود ذخیره کنید. برای شروع بدون خرید، مراحل راهنمای شروع سریع را انجام دهید.

قواعد نگهداری امن

• کلید را فقط از سرور یا worker مورد اعتماد ارسال کنید؛ آن را در اپ عمومی، HTML یا bundle جاوااسکریپت قرار ندهید؛
• کلید را در URL نگذارید، زیرا URL ممکن است در تاریخچه، لاگ، proxy، analytics و referrer ثبت شود؛
• مقدار کامل کلید را در گزارش خطا، screenshot یا پیام پشتیبانی نفرستید؛
• برای محیط های جدا کلیدهای جدا بسازید و کلید بلااستفاده را از پروفایل لغو کنید؛
• اگر احتمال افشا وجود دارد، کلید را فوری لغو و کلید جدید ایجاد کنید.

تفسیر پاسخ های احراز هویت

نبودن یا نامعتبر بودن کلید معمولا با 401 و code برابر AUTHENTICATION_FAILED برمی گردد. حساب منقضی یا بدون اشتراک فعال می تواند 403 بدهد. پایان سهمیه روزانه با 429 و code برابر DAILY_LIMIT_EXCEEDED مشخص می شود. جزئیات و ساختار پاسخ را در راهنمای خطاها و سهمیه ببینید.

نمونه JavaScript در بک اند

const response = await fetch("https://servix.cc/api/v1/assets/USD_RLS", {
  headers: { "X-API-Key": process.env.SERVIX_API_KEY }
});

if (!response.ok) {
  throw new Error("Servix request failed: " + response.status);
}

const price = await response.json();

برای مشاهده تمام عملیات مجاز مشتری، OpenAPI عمومی یا مجموعه Postman را دریافت کنید.