رفتن به محتوای اصلی
آلفاناDocs

احراز هویت Public API

ساخت، نگهداری و ارسال Account API Key و تفاوت آن با App Secret مورد استفاده SDK.

برای دسترسی به Public API آلفانا باید از Account API Key استفاده کنید. این کلید به حساب شما متصل است و درخواست‌های Server-side به endpointهای /api/v1/* را احراز هویت می‌کند.

Account API Key را می‌توانید از مسیر زیر در داشبورد آلفانا بسازید:

text
/dashboard/api-keys

مقدار کامل کلید با پیشوند alphana_api_ هنگام ساخت یا Rotate در اختیار شما قرار می‌گیرد.

این مقدار یک Credential سطح حساب است و باید فقط در محیط امن Server نگهداری شود. آن را داخل JavaScript مرورگر، Repository، فایل‌های عمومی، GTM یا Environment Variableهایی که وارد Bundle سمت Client می‌شوند قرار ندهید.

نگهداری API Key#

بهتر است Account API Key را در Secret Manager، Environment Variable سمت Server یا زیرساخت امن مشابه نگهداری کنید.

برای مثال:

env
ALPHANA_API_KEY=alphana_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

سپس برنامه Server-side می‌تواند این مقدار را در زمان ارسال درخواست بخواند.

از قرار دادن مستقیم کلید داخل Source Code خودداری کنید:

typescript
// این الگو را استفاده نکنید
const apiKey = "alphana_api_xxxxxxxxx";

در مقابل، مقدار را از Environment امن دریافت کنید:

typescript
const apiKey = process.env.ALPHANA_API_KEY;

این جداسازی کمک می‌کند Credential از کد Application جدا باقی بماند و هنگام انتشار Repository یا Build ناخواسته در دسترس قرار نگیرد.

ارسال API Key#

Public API از Bearer Authentication استفاده می‌کند.

کلید را در Header زیر ارسال کنید:

text
Authorization: Bearer YOUR_API_KEY

برای مثال، دریافت فهرست Appهای قابل‌دسترسی:

curl
curl --request GET \
  --url https://api.alphana.ir/api/v1/apps \
  --header "Authorization: Bearer $ALPHANA_API_KEY" \
  --header "Accept: application/json"

در این درخواست، مقدار واقعی کلید از Environment Variable با نام ALPHANA_API_KEY خوانده می‌شود.

اگر Credential معتبر باشد، API درخواست را در context همان حساب پردازش می‌کند.

دسترسی Account API Key#

یک Account API Key معتبر می‌تواند به Appهایی دسترسی داشته باشد که حساب مربوط به کلید اجازه مشاهده آن‌ها را دارد.

این مجموعه شامل:

  • Appهای متعلق به همان حساب
  • Appهایی که با همان کاربر Share شده‌اند

است.

بنابراین Public API فقط به Appهایی محدود می‌شود که همان حساب در آلفانا به آن‌ها دسترسی دارد.

برای مشاهده این Appها می‌توانید ابتدا endpoint زیر را فراخوانی کنید:

text
GET /api/v1/apps

سپس از id App موردنظر در درخواست‌های تحلیلی بعدی استفاده کنید.

استفاده از appId#

بسیاری از Queryهای تحلیلی Public API باید بدانند داده مربوط به کدام App است.

برای پیدا کردن شناسه صحیح، ابتدا Appهای قابل‌دسترسی را دریافت کنید:

curl
curl --request GET \
  --url https://api.alphana.ir/api/v1/apps \
  --header "Authorization: Bearer $ALPHANA_API_KEY" \
  --header "Accept: application/json"

در پاسخ، id مربوط به App موردنظر را پیدا کنید و همان مقدار را به‌عنوان appId در endpointهای تحلیلی استفاده کنید.

یعنی اگر پاسخ App شامل شناسه‌ای مثل:

text
app_123

باشد، همین مقدار مبنای درخواست‌های بعدی برای همان App خواهد بود.

بهتر است integration خود را بر اساس appId بسازید، نه نام نمایشی App؛ چون نام می‌تواند تغییر کند اما شناسه برای ارتباط API مناسب‌تر است.

تفاوت Credentialهای آلفانا#

در آلفانا چند نوع Credential با نقش‌های متفاوت وجود دارد. این مقادیر جای یکدیگر استفاده نمی‌شوند.

Credentialمحل استفاده
alphana_api_…Backend شما برای درخواست‌های Public API در مسیر /api/v1/*
App secretKeySDK مرورگر برای ingestion داده‌های همان App
JWTDashboard و APIهای مدیریت داخلی آلفانا

شناخت این تفاوت مهم است، چون هر Credential سطح دسترسی و کاربرد متفاوتی دارد.

Account API Key#

Account API Key با پیشوند زیر شروع می‌شود:

text
alphana_api_

این کلید برای دسترسی Server-side به Public API طراحی شده است.

برای مثال:

text
GET /api/v1/apps
POST /api/v1/apps

یا سایر endpointهای عمومی تحلیلی که در مستندات Public API معرفی شده‌اند.

این Credential در سطح حساب عمل می‌کند و نباید وارد SDK مرورگر شود.

App secretKey#

secretKey یک App نقش متفاوتی دارد.

این مقدار برای جریان SDK و ingestion همان App طراحی شده است و همراه appId در Tracker استفاده می‌شود.

برای مثال:

typescript
const tracker = new UserTracker({
  appId: "YOUR_APP_ID",
  secretKey: "YOUR_APP_SECRET",
});

این Credential با Account API Key یکسان نیست.

در نتیجه، این دو مقدار را با هم جایگزین نکنید:

text
Account API Key → Public API
App Secret       → SDK ingestion

اگر در حال نصب Tracker روی وب‌سایت هستید، از appId و secretKey همان App استفاده کنید.

اگر در Backend خودتان به Public API درخواست می‌فرستید، از Account API Key استفاده کنید.

JWT#

JWT برای Dashboard و APIهای مدیریت داخلی استفاده می‌شود.

این Credential بخشی از Session مدیریتی آلفاناست و برای integrationهای معمول Public API نباید جای Account API Key استفاده شود.

بنابراین اگر در حال ساخت یک integration خارجی یا Server-side هستید، مسیر صحیح Public API همان Bearer Authentication با Account API Key است.

نمونه درخواست از Backend#

در یک Backend JavaScript می‌توانید ساختار درخواست را به این شکل پیاده کنید:

typescript
const response = await fetch("https://api.alphana.ir/api/v1/apps", {
  headers: {
    Authorization: `Bearer ${process.env.ALPHANA_API_KEY}`,
    Accept: "application/json",
  },
});

const apps = await response.json();

API Key در این مثال فقط در محیط Server خوانده می‌شود و وارد JavaScript مرورگر نمی‌شود.

اگر Framework شما هم Server و هم Client Code دارد، مطمئن شوید این درخواست در بخش Server-side اجرا می‌شود.

Next.js#

در Next.js Account API Key را در متغیر خصوصی Server قرار دهید:

env
ALPHANA_API_KEY=alphana_api_xxxxxxxxx

و نه در متغیری با پیشوند:

env
NEXT_PUBLIC_

برای مثال:

typescript
const apiKey = process.env.ALPHANA_API_KEY;

متغیرهای NEXT_PUBLIC_ می‌توانند وارد Bundle مرورگر شوند و برای نگهداری Account API Key مناسب نیستند.

Credentialهای App SDK می‌توانند بر اساس قرارداد SDK در Client استفاده شوند، اما Account API Key باید از این جریان جدا بماند.

Rotate کردن کلید#

هنگام ساخت یا Rotate کردن Account API Key، مقدار کامل Credential در اختیار شما قرار می‌گیرد.

بعد از دریافت کلید جدید، آن را در Secret Store مورد استفاده Backend جایگزین کنید و مطمئن شوید سرویس‌هایی که به Public API متصل هستند از مقدار جدید استفاده می‌کنند.

بهتر است Credentialها را در یک نقطه مشخص مدیریت کنید تا تغییر کلید نیازمند ویرایش مستقیم Source Code یا چند فایل مختلف نباشد.

برای مثال:

text
Secret Manager
        ↓
ALPHANA_API_KEY
        ↓
Backend
        ↓
Public API

این ساختار مدیریت Credential و Rotate کردن آن را ساده‌تر می‌کند.

از ثبت API Key در Log خودداری کنید#

هنگام Debug کردن درخواست‌های Public API، Header کامل Authorization را در Log ثبت نکنید.

برای مثال، این اطلاعات نباید در خروجی Application ظاهر شوند:

text
Authorization: Bearer alphana_api_xxxxx...

در صورت نیاز به Debugging، فقط اطلاعاتی را ثبت کنید که برای بررسی Request کافی هستند؛ مثل endpoint، status code یا شناسه App.

همین اصل برای Error Tracking، CI/CD و ابزارهای Monitoring نیز برقرار است.

MCP و API Key#

سرویس MCP مستندات آلفانا برای خواندن Public Docs طراحی شده است و برای استفاده از مستندات عمومی به Account API Key نیاز ندارد.

Account API Key خود را در Config، Prompt یا درخواست‌های مربوط به MCP مستندات قرار ندهید.

MCP باید بتواند قرارداد Public API را برای دستیار هوش مصنوعی توضیح دهد، اما Credential واقعی حساب شما بخشی از مستندات نیست.

در نتیجه:

text
MCP → مستندات عمومی
Public API → داده حساب با Account API Key

این دو جریان را از یکدیگر جدا نگه دارید.

جریان پیشنهادی احراز هویت#

برای استفاده از Public API، این مسیر را دنبال کنید:

  1. از /dashboard/api-keys یک Account API Key بسازید.
  2. مقدار کامل alphana_api_… را در Secret Manager سمت Server ذخیره کنید.
  3. کلید را در Header Authorization: Bearer ارسال کنید.
  4. با GET /api/v1/apps Appهای قابل‌دسترسی را دریافت کنید.
  5. id App موردنظر را به‌عنوان appId در Queryهای تحلیلی استفاده کنید.
  6. Account API Key را از App secretKey و JWT جدا نگه دارید.
  7. Credentialها را در Log، Repository یا Client-side Code قرار ندهید.