پرش به مطلب اصلی

توکن، رفرش‌توکن و سشن

در این روش، کاربر با شماره‌ی موبایل خود وارد می‌شود و برنامه‌ی شما یک Access Token کوتاه‌مدت و یک Refresh Token دریافت می‌کند. Access Token در هدر Authorization: Bearer فرستاده می‌شود و پس از انقضا با Refresh Token نوسازی می‌گردد. این روش برای نرم‌افزارهای چندمشتری مناسب است؛ الگوی کامل آن در اتصال برنامه‌های چندمشتری آمده است.

هدرهای مشترک​

هر سه endpoint این صفحه به هدرهای زیر نیاز دارند:

هدرتوضیحالزامی
X-Client-Appکلید ClientApp که پشتیبانی به شما داده استبله
X-Session-Keyکلید یکتای سشن همان مشتریبله، در هر سه endpoint

اگر X-Client-App ارسال نشود، پاسخ 401 برمی‌گردد. اگر X-Session-Key در verify یا register نباشد، پاسخ 400 با پیام «Session Key not found!» است. برای token نیز همیشه X-Session-Key را بفرستید؛ نبودن آن باعث خطای سرور می‌شود.

گام ۱: شروع ورود (verify)​

این endpoint یک پیامک تأیید به شماره‌ی کاربر می‌فرستد و شناسه‌ی ارجاع را برمی‌گرداند.

POST /auth/api/verify

بدنه‌ی درخواست

فیلدنوعالزامیتوضیح
phoneNumberرشتهبلهشماره‌ی موبایل کاربر، حداقل ۱۱ رقم
curl -X POST "https://api.payavasms.com/auth/api/verify" \
-H "X-Client-App: YOUR_CLIENT_APP_KEY" \
-H "X-Session-Key: YOUR_SESSION_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "09120000000"
}'

نمونه‌ی پاسخ موفق

{
"isError": false,
"errorMessage": "",
"client": "YOUR_CLIENT_ID",
"phoneNumber": "09120000000",
"referenceId": "3f2b8c1e-0000-0000-0000-000000000000"
}

فیلدهای پاسخ

فیلدنوعتوضیح
isErrorبولیtrue در صورت خطا
errorMessageرشتهمتن خطا، در حالت موفق خالی
clientرشتهشناسه‌ی کلاینت
phoneNumberرشتهشماره‌ی ورودی
referenceIdرشتهشناسه‌ی ارجاع برای مرحله‌ی بعد

خطاها

خطاها با isError برابر true و پیام فارسی در errorMessage برگردانده می‌شوند:

پیامعلت
شماره تلفن وارد شده معتبر نمی باشد.شماره کمتر از ۱۱ رقم است
کلید وارد شده معتبر نمی باشد.مقدار X-Client-App شناخته نمی‌شود
کاربری با این شماره موبایل پیدا نشدبرای این شماره حسابی در پایاوا وجود ندارد
خطا در اعتبار سنجیX-Session-Key با سشن ثبت‌شده‌ی کاربر مطابقت ندارد
دسترسی غیرمجاز درخواست مسدود شدآی‌پی یا سشن مسدود شده است
خطا در ارسال پیامکارسال پیامک تأیید ناموفق بود

گام ۲: تکمیل ورود (register)​

کد پیامک‌شده را همراه شناسه‌ی ارجاع بفرستید تا توکن‌ها صادر شوند و سشن ثبت گردد.

POST /auth/api/register

بدنه‌ی درخواست

فیلدنوعالزامیتوضیح
referenceIdرشتهبلهمقدار برگشتی از verify
codeرشتهبلهکد تأییدی که با پیامک آمده است
curl -X POST "https://api.payavasms.com/auth/api/register" \
-H "X-Client-App: YOUR_CLIENT_APP_KEY" \
-H "X-Session-Key: YOUR_SESSION_KEY" \
-H "Content-Type: application/json" \
-d '{
"referenceId": "3f2b8c1e-0000-0000-0000-000000000000",
"code": "123456"
}'

نمونه‌ی پاسخ موفق

{
"isError": false,
"errorMessage": null,
"accessToken": "YOUR_ACCESS_TOKEN",
"refreshToken": "YOUR_REFRESH_TOKEN",
"client": "YOUR_CLIENT_ID",
"expireInSeconds": 3600,
"expireAtUtc": "2026-11-19T12:00:00.0000000Z"
}

فیلدهای پاسخ (مشترک بین register و token)

فیلدنوعتوضیح
isErrorبولیtrue در صورت خطا
errorMessageرشتهمتن خطا
accessTokenرشتهتوکن دسترسی برای هدر Authorization
refreshTokenرشتهتوکن نوسازی
clientرشتهشناسه‌ی کلاینت
expireInSecondsعددمدت اعتبار accessToken به ثانیه
expireAtUtcرشتهزمان دقیق انقضا به UTC با قالب ISO 8601

خطاها

پیامعلت
کد ارجاع ورودی نامعتبر است!referenceId وجود ندارد یا قبلاً استفاده شده است
کد وارد شده اشتباه می باشد!code درست نیست
کلید وارد شده معتبر نمی باشد.X-Client-App شناخته نمی‌شود

گام ۳: نوسازی توکن (token)​

با Refresh Token، بدون ورود مجدد، توکن جدید بگیرید. همان X-Session-Key ورود را بفرستید.

POST /auth/api/token

بدنه‌ی درخواست

فیلدنوعالزامیتوضیح
refreshTokenرشتهبلهآخرین Refresh Token دریافت‌شده
curl -X POST "https://api.payavasms.com/auth/api/token" \
-H "X-Client-App: YOUR_CLIENT_APP_KEY" \
-H "X-Session-Key: YOUR_SESSION_KEY" \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "YOUR_REFRESH_TOKEN"
}'

نمونه‌ی پاسخ موفق

{
"isError": false,
"errorMessage": null,
"accessToken": "YOUR_NEW_ACCESS_TOKEN",
"refreshToken": "YOUR_NEW_REFRESH_TOKEN",
"client": "YOUR_CLIENT_ID",
"expireInSeconds": 3600,
"expireAtUtc": "2026-11-19T13:00:00.0000000Z"
}

خطاها

پیامعلت
مقدار رفرش توکن وارد نشده.refreshToken خالی است
کلید وارد شده معتبر نمی باشد.X-Client-App شناخته نمی‌شود
اشتراک شما منقضی شده است. لطفا برای تمدید آن اقدام فرمایید.اشتراک کاربر تمام شده است
متن خطای سرویس هویت‌سنجیRefresh Token نامعتبر یا ابطال‌شده است

راهکار پیشنهادی مدیریت توکن​

مدت اعتبار توکن‌ها ممکن است تغییر کند؛ بنابراین هیچ مقدار ثابتی را در برنامه‌ی خود فرض نکنید و فقط از مقدارهای برگشتی همین پاسخ‌ها استفاده کنید. روش پیشنهادی:

  1. پس از هر register و هر token، علاوه بر accessToken و refreshToken، زمان دقیق انقضا (expireAtUtc) را هم ذخیره کنید.
  2. پیش از هر درخواست به API، زمان انقضا را با زمان فعلی بسنجید. اگر گذشته است (یا کمتر از یک دقیقه مانده)، ابتدا نوسازی کنید و سپس درخواست را بفرستید.
  3. اگر با وجود بررسی بالا پاسخ 401 گرفتید (مثلاً توکن ابطال شده است)، یک بار نوسازی کنید و درخواست را تکرار کنید. اگر نوسازی هم خطا داد، کاربر باید دوباره با verify و register وارد شود.
  4. پس از هر نوسازی، مقدار تازه‌ی refreshToken را جایگزین قبلی کنید.
  5. نوسازی را برای هر مشتری جداگانه و پشت یک قفل انجام دهید تا دو درخواست هم‌زمان باعث چند نوسازی نشوند.

نمونه‌ی زیر این منطق را پیاده می‌کند. ذخیره‌سازی پایدار (پایگاه داده یا فایل رمزنگاری‌شده) را متناسب با برنامه‌ی خود جایگزین کنید.

using System.Net;
using System.Net.Http.Json;

public sealed class TokenState
{
public string AccessToken { get; set; } = "";
public string RefreshToken { get; set; } = "";
public DateTimeOffset ExpireAtUtc { get; set; }
}

public sealed class PayavaClient(HttpClient http, TokenState state, string clientAppKey, string sessionKey)
{
private static readonly TimeSpan Skew = TimeSpan.FromSeconds(60);
private readonly SemaphoreSlim _lock = new(1, 1);

public async Task<HttpResponseMessage> SendAsync(Func<HttpRequestMessage> build)
{
if (DateTimeOffset.UtcNow >= state.ExpireAtUtc - Skew)
await RefreshAsync();

var response = await http.SendAsync(Authorize(build()));
if (response.StatusCode != HttpStatusCode.Unauthorized)
return response;

await RefreshAsync(force: true);
return await http.SendAsync(Authorize(build()));
}

private HttpRequestMessage Authorize(HttpRequestMessage request)
{
request.Headers.Add("Authorization", "Bearer " + state.AccessToken);
return request;
}

private async Task RefreshAsync(bool force = false)
{
await _lock.WaitAsync();
try
{
if (!force && DateTimeOffset.UtcNow < state.ExpireAtUtc - Skew) return;

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.payavasms.com/auth/api/token")
{
Content = JsonContent.Create(new { refreshToken = state.RefreshToken })
};
request.Headers.Add("X-Client-App", clientAppKey);
request.Headers.Add("X-Session-Key", sessionKey);

var result = await (await http.SendAsync(request)).Content.ReadFromJsonAsync<TokenResult>();
if (result is null || result.IsError)
throw new InvalidOperationException(result?.ErrorMessage ?? "Token refresh failed");

state.AccessToken = result.AccessToken!;
state.RefreshToken = result.RefreshToken!;
state.ExpireAtUtc = DateTimeOffset.Parse(result.ExpireAtUtc!);
// اینجا state را در محل ذخیره‌سازی پایدار بنویسید
}
finally { _lock.Release(); }
}

private sealed record TokenResult(bool IsError, string? ErrorMessage, string? AccessToken,
string? RefreshToken, string? ExpireAtUtc);
}