احراز هویت

نسخهٔ 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 عمل می‌کند از اعطای کد مجوز استفاده می‌کند. مرورگر کاربر را به نشانی URL مجوز بفرستید، همراه با 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 می‌گیرد و دوباره مبادله می‌کند. تنها رمز یک کلاینت را نمی‌توان باطل کرد: ابتدا جایگزینش را بسازید، یا کلاینت را حذف کنید.

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