د هویت تایید

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

د Lingara API هره غوښتنه د لاسرسي یو ټوکن لېږدوي. سرور دا ټوکن د ټوکن په پای ټکي کې د OAuth د یوه پېرودونکي د پېژند او راز په بدلولو ترلاسه کوي: دا د OAuth 2.0 د client credentials اجازه ده، د هغه سرور لپاره چې د ځان په استازیتوب کار کوي. پېرودونکي د Lingara وېب اپ د یوځای کېدنو په پاڼه کې جوړ کړئ، په app.getlingara.com/admin کې.

سیشن که پېرودونکی

د Lingara اپونه تاسو په یوه سیشن ننباسي، چې ټولې ساحې لري او ستاسو د پلان له ونډې لګوي. پېرودونکی محدود دی: کله چې یې جوړوئ هغه ساحې ټاکئ چې ورته اجازه لري، او د لاسرسي هر ټوکن چې یې ترلاسه کوي یوازې هغه ساحې لري چې غوښتي یې دي.

درې ارزښتونه

د پېرودونکي پېژند په lgr_cid_ پیلېږي او د ټوکن په پای ټکي کې پېرودونکی نوموي. دا راز نه دی.

د پېرودونکي راز په lgr_cs_ پیلېږي او یوازې د ټوکن پای ټکي ته لېږل کېږي. یوازې یو ځل ښودل کېږي، کله چې یې جوړوئ: همغه وخت یې کاپي کړئ، ځکه Lingara یوازې د هغه هش ساتي.

د لاسرسي ټوکن په lgr_at_ پیلېږي او یو ساعت دوام کوي. د /v1/ لاندې غوښتنو په Authorization: Bearer سرلیک کې ځي، او بل هېڅ ځای کې نه. دا یوازینی ارزښت دی چې په هغه سرلیک کې ځای لري: د پېرودونکي راز چې هلته ولېږل شي په 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}، نه د /v1/ د {code, error} په پاکټ کې. غلط یا لغوه شوی راز، یا ړنګ شوی پېرودونکی، په 401 او invalid_client ردېږي. هغه ساحه چې پېرودونکی یې د غوښتلو اجازه نه لري ټوله بدلونه په 400 او invalid_scope ردوي؛ هېڅکله په چوپه خوله نه محدودېږي.

د Lingara د بل کارن په استازیتوب کار وکړئ

هغه اپ چې د Lingara د بل کارن په استازیتوب کار کوي د اجازې کوډ ډول اجازه کاروي. د کارن براوزر د اجازې پتې ته ولېږئ، له response_type=code، client_id، یو redirect_uri چې دقیقاً له هغو څخه له یوې سره برابر وي چې تاسو ثبت کړې، scope، state او یو S256 code_challenge سره. کارن د 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/ هېڅ cross-origin 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/ او نه د ټوکن پای ټکی هېڅ cross-origin preflight ته ځواب ورکوي، نو په بل سایټ کې براوزر په هر حال دوی نشي بللی.

د پېرودونکو مدیریت

د یوځای کېدنو په پاڼه کې، په app.getlingara.com/admin کې، پېرودونکي جوړ کړئ، نومونه یې بدل کړئ او ړنګ یې کړئ، بدل کړئ چې هر یو یې څه کولی شي او کومې نسخې ته تړل شوی، او د هغه رازونه جوړ او لغوه کړئ. د پېرودونکي ړنګول سمدستي د هغه د لاسرسي ټول ټوکنونه دروي، او هغه اجازه پای ته رسوي چې هر کارن ورته ورکړې ده. د یوه راز لغوه کول سمدستي د لاسرسي هغه ټول ټوکنونه دروي چې په هغه راز بدل شوي وو. د پېرودونکي د ساحو محدودول هم سمدستي پلي کېږي؛ د هغو پراخول، یا د نسخې بدلول، له راتلونکې بدلونې پلي کېږي.

د راز بدلول

یو پېرودونکی په یوه وخت کې دوه رازونه لرلی شي. د بدلولو لپاره، نوی راز جوړ کړئ، ځای پر ځای یې کړئ، او زوړ یې هغه وخت لغوه کړئ چې د یوځای کېدنو په پاڼه کې د هغه «وروستی ځل کارول شوی» نېټه نور نه بدلېږي. هغه پروسه چې نوی راز یې لري خو لا هم د زاړه راز ټوکن ساتي یو ځل 401 ترلاسه کوي او بیا بدلونه کوي. د پېرودونکي یوازینی راز نشي لغوه کېدای: لومړی یې بدیل جوړ کړئ، یا پېرودونکی ړنګ کړئ.

که یوه ژباړه له انګلیسي مرجع سره توپیر ولري، انګلیسي مرجع سمه ده.