تصدیق هویت

نسخهٔ API 2026-10-affable-towhee

هر فراخوانی Lingara API یک توکن دسترسی با خود دارد. سرور توکن دسترسی را با تبادلهٔ شناسه و رمز یک کلاینت OAuth در نقطهٔ پایانی توکن به دست می‌آورد: همان اعطای client credentials در OAuth 2.0، برای سروری که از طرف خودش عمل می‌کند. کلاینت‌ها را در صفحهٔ یکپارچه‌سازی‌ها در نسخهٔ ویب Lingara، به آدرس app.getlingara.com/admin، ایجاد کنید.

جلسه یا کلاینت

اپلیکیشن‌های Lingara شما را با یک جلسه وارد می‌کنند که همهٔ حوزه‌های دسترسی را دارد و از سهمیهٔ اشتراک شما مصرف می‌کند. کلاینت محدودتر است: هنگام ایجاد آن، حوزه‌های دسترسی مجازش را انتخاب می‌کنید و هر توکن دسترسی که می‌گیرد تنها حوزه‌هایی را دارد که درخواست می‌کند.

سه مقدار

شناسهٔ کلاینت با lgr_cid_ شروع می‌شود و کلاینت را در نقطهٔ پایانی توکن معرفی می‌کند. این شناسه محرم نیست.

رمز کلاینت با lgr_cs_ شروع می‌شود و تنها به نقطهٔ پایانی توکن فرستاده می‌شود. تنها یک بار، هنگام ایجاد، نشان داده می‌شود: همان وقت آن را کاپی کنید، زیرا Lingara تنها هش آن را نگه می‌دارد.

توکن دسترسی با lgr_at_ شروع می‌شود و یک ساعت اعتبار دارد. جای آن در هِدِر Authorization: Bearer فراخوانی‌های زیر /v1/ است و نه هیچ جای دیگر. تنها مقداری است که در آن هِدِر جای دارد: رمز کلاینتی که آنجا فرستاده شود با 401 رد می‌شود.

گرفتن توکن دسترسی

یک فورم را با POST به نقطهٔ پایانی توکن بفرستید، همراه با grant_type=client_credentials. شناسه و رمز کلاینت را یا با تصدیق هویت HTTP Basic بفرستید یا در فیلدهای فورم client_id و client_secret، هرگز هر دو. scope لستی جداشده با فاصله از حوزه‌های دسترسی مجاز کلاینت است؛ اگر آن را نفرستید، همهٔ حوزه‌های مجاز کلاینت را می‌گیرید. فرمان زیر تنها usage:read را درخواست می‌کند، حوزه‌ای که نمونهٔ GET /v1/usage در ادامه به آن نیاز دارد.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

پاسخ شامل access_token، token_type (Bearer)، expires_in (3600، به ثانیه) و scope است، یعنی حوزه‌هایی که توکن واقعاً دارد. تبادلهٔ ناموفق در قالب خطای OAuth پاسخ می‌دهد، {error, error_description}، نه در پاکت {code, error} مسیرهای /v1/. رمز نادرست یا باطل‌شده، یا کلاینت حذف‌شده، با 401 و invalid_client رد می‌شود. حوزه‌ای که کلاینت اجازهٔ درخواستش را ندارد کل تبادله را با 400 و invalid_scope رد می‌کند؛ هرگز بی‌صدا محدود نمی‌شود.

از جانب کاربر دیگر Lingara کار کنید

اپلیکیشنی که از جانب کاربر دیگر Lingara کار می‌کند از اعطای کود اجازه استفاده می‌کند. براوزر کاربر را به آدرس اجازه بفرستید، همراه با response_type=code، client_id، یک redirect_uri که دقیقاً با یکی از آدرس‌هایی که ثبت کرده‌اید مطابقت داشته باشد، scope، state و یک code_challenge از نوع S256. کاربر صفحهٔ رضایت Lingara را می‌بیند و با code، state و iss به redirect_uri شما برمی‌گردد. پیش از استفاده از کود، بررسی کنید که state همان است که فرستاده‌اید و iss برابر با https://api.getlingara.com است.

PKCE الزامی است

همهٔ کلاینت‌ها از PKCE استفاده می‌کنند، و تنها با روش S256. یک code_verifier تصادفی بسازید، هش SHA-256 آن را با کدگذاری base64url به حیث code_challenge همراه با code_challenge_method=S256 بفرستید، و خود آن را برای تبادله نگه دارید. درخواستی که روشی نداشته باشد، یا روش آن plain باشد، با invalid_request رد می‌شود.

تبادلهٔ کود

در ظرف 60 ثانیه، با POST به نقطهٔ پایانی توکن درخواست بفرستید، همراه با grant_type=authorization_code، code، همان redirect_uri و code_verifier، و به حیث کلاینت تصدیق هویت کنید؛ کلاینت عمومی تنها client_id را می‌فرستد. پاسخ یک refresh_token نیز دارد که با lgr_rt_ شروع می‌شود. کود با lgr_ac_ شروع می‌شود و تنها یک بار کار می‌کند: استفادهٔ دوم با invalid_grant رد می‌شود و توکن‌هایی را که تبادلهٔ اول صادر کرده بود از کار می‌اندازد.

تازه‌سازی

وقتی توکن دسترسی منقضی شد، با POST به نقطهٔ پایانی توکن درخواست بفرستید، همراه با grant_type=refresh_token و refresh_token، و دوباره به حیث کلاینت تصدیق هویت کنید. هر تازه‌سازی یک توکن تازه‌سازی جدید برمی‌گرداند: تنها جدیدترین را نگه دارید. تازه‌سازی‌های خود را یکی پس از دیگری انجام دهید: توکن تازه‌سازی کهنه‌ای که بیش از 60 ثانیه پس از جایگزین شدنش استفاده شود دزدی‌شده شمرده می‌شود و توکن‌های آن نصب را با invalid_grant از کار می‌اندازد. توکن تازه‌سازی‌ای که 30 روز استفاده نشود منقضی می‌شود. نقطهٔ پایانی توکن تعداد درخواست‌ها را برای هر آدرس محدود می‌کند، پس تنها وقتی توکنی تمام شد آن را تازه کنید.

اپلیکیشن‌های بومی کلاینت عمومی هستند

اپلیکیشن دسکتاپ، موبایل یا خط فرمان نمی‌تواند رمزی را پنهان نگه دارد، پس کلاینت عمومی است: رمزی ندارد، تنها client_id را به نقطهٔ پایانی توکن می‌فرستد، و یک آدرس برگشت محلی (loopback) مانند http://127.0.0.1/callback (با هر پورت) یا یک طرح خصوصی مانند com.example.app:/callback ثبت می‌کند. کاربر هر بار صفحهٔ رضایت را می‌بیند. صفحهٔ ویب نمی‌تواند کلاینت باشد: نه نقطهٔ پایانی توکن و نه /v1/ به درخواست preflight میان‌مبدأ پاسخ نمی‌دهند.

وقتی کاربر اپلیکیشن شما را حذف می‌کند

کاربر می‌تواند هر زمان اپلیکیشن شما را در «اپلیکیشن‌های وصل‌شده» حذف کند، یا اگر آن را نصب کرده باشد با لغو نصب آن، و فراخوانی بعدی آن با 401 ناکام می‌شود. وقتی کاربر از اپلیکیشن شما خارج می‌شود، توکن تازه‌سازی آن را در نقطهٔ پایانی ابطال باطل کنید، که توکن‌های آن نصب را از کار می‌اندازد.

وقتی توکن منقضی می‌شود

پس از یک ساعت، /v1/ با 401، کود unauthorized و خطایی که با invalid_token شروع می‌شود پاسخ می‌دهد. وقتی فراخوانی‌ای 401 گرفت، یا کمی پیش از تمام شدن expires_in، دوباره تبادله کنید و فراخوانی را یک بار تکرار کنید. اگر خود تبادله با invalid_client یا invalid_scope ناکام شود، کلاینت حذف، رمزش باطل یا حوزه‌هایش محدود شده است: توقف کنید و آن را در صفحهٔ یکپارچه‌سازی‌ها درست کنید، زیرا تلاش دوباره نمی‌تواند موفق شود. توکن را میان فراخوانی‌ها نگه دارید: نقطهٔ پایانی توکن تعداد تبادله‌ها را برای هر کلاینت و هر آدرس محدود می‌کند و برنامه‌ای که در هر فراخوانی تبادله کند در همان ساعت با 429 و rate_limited رد می‌شود (منتظر Retry-After بمانید). این اعطا توکن تازه‌سازی ندارد: رمز دوباره تبادله می‌شود.

توکن‌های دسترسی تنها به مسیرهای API می‌رسند

توکن دسترسی تنها روی مسیرهای زیر /v1/ کار می‌کند. اگر به هر مسیر دیگر Lingara فرستاده شود، با 401 رد می‌شود و بدنهٔ پاسخ با api_token_not_accepted شروع می‌شود، به شکل متن ساده یا داخل فیلد error، و هرگز در پاکت {code, error} که مسیرهای /v1/ استفاده می‌کنند. توکن دسترسی را مانند نمونهٔ زیر در هِدِر Authorization بفرستید.

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

حوزه‌های دسترسی

هر عملیات دقیقاً به یک حوزهٔ دسترسی نیاز دارد که در صفحهٔ همان عملیات نام برده شده است. توکن دسترسی که آن حوزه را نداشته باشد با 403 و کود insufficient_scope رد می‌شود. برای فراخوانی عملیات، اگر کلاینت مجاز به آن حوزه است، هنگام تبادله آن را درخواست کنید. جدول زیر هر حوزه و عملیاتی را که اجازه می‌دهد فهرست می‌کند.

مصرف فراخوانی را چه کسی می‌پردازد

هر کلاینت به یکی از دو روش صورت‌حساب می‌شود که هنگام ایجاد آن انتخاب می‌شود. کلاینت allowance از سهمیهٔ مالک خود مصرف می‌کند، همان سهمیه‌ای که اپلیکیشن‌های شما مصرف می‌کنند، و توکن‌های دسترسی آن نیز از همان مصرف می‌کنند؛ GET /v1/usage مقدار باقی‌مانده را نشان می‌دهد. کلاینت metered از هیچ سهمیه‌ای مصرف نمی‌کند: به ازای هر اعتبار، از طریق اشتراک صورت‌حساب مصرفی‌ای که در صفحهٔ یکپارچه‌سازی‌ها تنظیم می‌کنید، صورت‌حساب می‌شود. فراخوانی‌های آن وقتی کلاینت یا حساب شما به سقف مصارف ماهانهٔ خود برسد با 402 و spend_cap_reached رد می‌شوند، و تا زمانی که صورت‌حساب مصرفی فعال نباشد با 402 و metered_billing_inactive. یک پلان درسی 10 اعتبار است، یک نوبت گفتگو با معلم خصوصی 1 اعتبار و یک ساختن لغات 3 اعتبار، پس unitsی که GET /v1/usage گزارش می‌دهد با همین وزن‌ها به اعتبار تبدیل می‌شود. فراخوانی‌ای که اپلیکیشن با توکنی از کود اجازه از جانب کاربر دیگری انجام می‌دهد، همیشه از سهمیهٔ همان کاربر مصرف می‌کند، صرف نظر از حالت کلاینت.

رمزها و توکن‌ها را روی سرور نگه دارید

جای رمز کلاینت روی سروری است که در اختیار شماست، هرگز در صفحهٔ ویب، افزونهٔ براوزر یا بستهٔ اپلیکیشن، جایی که هر کسی می‌تواند آن را بخواند. اپلیکیشن بومی کلاینت عمومی است و هیچ رمزی نگه نمی‌دارد. نه /v1/ و نه نقطهٔ پایانی توکن به هیچ درخواست preflight میان‌مبدأ پاسخ نمی‌دهند، پس براوزری در سایت دیگر به هر حال نمی‌تواند آن‌ها را فراخوانی کند.

مدیریت کلاینت‌ها

در صفحهٔ یکپارچه‌سازی‌ها، به آدرس app.getlingara.com/admin، کلاینت‌ها را ایجاد کنید، نامشان را تغییر دهید و حذفشان کنید، تعیین کنید هر کدام چه کاری می‌تواند بکند و به کدام نسخه بسته شده است، و رمزهایش را ایجاد و باطل کنید. حذف کردن یک کلاینت همهٔ توکن‌های دسترسی آن را فوراً از کار می‌اندازد و اجازه‌ای را که هر کاربر به آن داده است پایان می‌دهد. باطل کردن یک رمز همهٔ توکن‌های دسترسی را که با آن رمز تبادله شده‌اند فوراً از کار می‌اندازد. محدود کردن حوزه‌های یک کلاینت نیز فوراً اعمال می‌شود؛ گسترش آن‌ها، یا تغییر نسخه‌اش، از تبادلهٔ بعدی اعمال می‌شود.

چرخاندن رمز

یک کلاینت می‌تواند هم‌زمان دو رمز داشته باشد. برای چرخاندن، رمز جدیدی ایجاد کنید، آن را مستقر کنید و رمز قدیمی را وقتی تاریخ «آخرین استفاده»‌اش در صفحهٔ یکپارچه‌سازی‌ها دیگر تغییر نمی‌کند باطل کنید. پروسه‌ای که رمز جدید را دارد اما هنوز توکنی از رمز قدیمی نگه داشته، یک بار 401 می‌گیرد و دوباره تبادله می‌کند. تنها رمز یک کلاینت را نمی‌توان باطل کرد: نخست جایگزینش را ایجاد کنید، یا کلاینت را حذف کنید.

اگر ترجمه با مرجع انگلیسی فرق داشته باشد، مرجع انگلیسی درست است.