رفتن به محتوای اصلی
آلفانا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

استفاده از 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 قرار ندهید.

Endpointهای قابل استفاده

Method و Pathکاربردپارامترهاپاسخ
POST/api/v1/appsساخت اپلیکیشن
اپ رهگیری‌شونده‌ای با مالکیت حساب کلید API می‌سازد.		body: CreateAppDto شامل name و domain201 با مشخصات app و secretKey تازه
GET/api/v1/appsفهرست اپلیکیشن‌ها
appهای owned و shared قابل‌دسترسی را بدون secretKey فهرست می‌کند.		—200 با آرایه PublicAppSummaryDto
GET/api/v1/sessions/data-boundsکران زمانی داده
قدیمی‌ترین و جدیدترین session timestamp یا null را می‌دهد.		appId: UUID اجباری200 با oldest و newest
GET/api/v1/sessions/overview/extendedنمای کلی توسعه‌یافته
معیارهای session، page، interaction، technology، error و traffic را برمی‌گرداند.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با PublicExtendedOverviewResponseDto
GET/api/v1/sessions/overview/kpisKPIهای نشست
current، previous و change برای معیارهای کلیدی را می‌دهد.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با PublicOverviewKpiResponseDto
GET/api/v1/sessions/pageviewsبازدید صفحه
views و sessionهای یکتای مشاهده‌کننده را به تفکیک path می‌دهد.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با آرایه PublicPageViewDto
GET/api/v1/sessions/timespentزمان حضور
زمان کل و میانگین به تفکیک path و برحسب میلی‌ثانیه را می‌دهد.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با آرایه PublicTimeSpentDto
GET/api/v1/sessions/user-growthرشد روزانه مخاطب
session، visitor، pageview و click روزانه UTC را می‌دهد.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با آرایه PublicUserGrowthPointDto
GET/api/v1/sessions/traffic-heatmapنقشه ترافیک
ماتریس ساعتی هفت روز اخیر در Asia/Tehran را می‌دهد.		appId: UUID اجباری200 با PublicTrafficHeatmapResponseDto
GET/api/v1/sessions/traffic-audience-activityفعالیت مخاطب
میانگین روز و ساعت در پنجره غلتان ۲۸ روز تهران را می‌دهد.		appId: UUID اجباری200 با PublicAudienceActivityResponseDto
GET/api/v1/sessions/locations/allموقعیت نشست‌ها
locationهای دارای مختصات را تجمیع و بر اساس count مرتب می‌کند.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با آرایه PublicLocationDto
GET/api/v1/growth/utmعملکرد UTM
حداکثر ۱۰۰ ترکیب UTM دارای source را با sessions و visitors می‌دهد.		appId: UUID اجباریfrom?: ISO 8601 شاملto?: ISO 8601 شامل200 با آرایه PublicUtmCampaignDto