Uthibitishaji

Toleo la API 2026-10-affable-towhee

Kila ombi kwa API ya Lingara hubeba tokeni ya ufikiaji. Seva huipata kwa kubadilisha kitambulisho cha mteja wa OAuth na siri yake kwenye sehemu ya mwisho ya tokeni: ruzuku ya client credentials ya OAuth 2.0, kwa seva inayojiwakilisha yenyewe. Unda wateja kwenye ukurasa wa Miunganisho wa programu ya wavuti ya Lingara, katika app.getlingara.com/admin.

Kipindi au mteja

Programu za Lingara hukuingiza kwa kipindi, ambacho kina kila wigo na hutumia kiwango cha matumizi cha mpango wako. Mteja ana mipaka zaidi: unachagua wigo anaoruhusiwa unapomuunda, na kila tokeni ya ufikiaji anayopata hubeba tu wigo anaouomba.

Thamani tatu

Kitambulisho cha mteja huanza na lgr_cid_ na humtaja mteja kwenye sehemu ya mwisho ya tokeni. Si siri.

Siri ya mteja huanza na lgr_cs_ na hutumwa tu kwenye sehemu ya mwisho ya tokeni. Huonyeshwa mara moja, unapoiunda: inakili wakati huo, kwa sababu Lingara huhifadhi hash yake pekee.

Tokeni ya ufikiaji huanza na lgr_at_ na hudumu saa moja. Huwekwa kwenye kichwa cha Authorization: Bearer cha maombi yaliyo chini ya /v1/, na si mahali pengine popote. Ndiyo thamani pekee inayofaa kwenye kichwa hicho: siri ya mteja ikitumwa hapo hukataliwa kwa 401.

Pata tokeni ya ufikiaji

Tuma fomu kwa POST kwenye sehemu ya mwisho ya tokeni ikiwa na grant_type=client_credentials. Tuma kitambulisho cha mteja na siri ama kwa uthibitishaji wa HTTP Basic au kama sehemu za fomu client_id na client_secret, kamwe si zote mbili. scope ni orodha ya wigo anaoruhusiwa mteja, iliyotenganishwa kwa nafasi; iache ili upate kila wigo anaoruhusiwa mteja. Amri iliyo hapa chini inaomba usage:read pekee, wigo unaohitajika na mfano wa GET /v1/usage ulio chini zaidi.

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"

Jibu hubeba access_token, token_type (Bearer), expires_in (3600, kwa sekunde) na scope, yaani wigo ambao tokeni inashikilia kwa kweli. Ubadilishaji ulioshindwa hujibu kwa muundo wa hitilafu wa OAuth, {error, error_description}, si kwa bahasha ya {code, error} ya /v1/. Siri isiyo sahihi au iliyobatilishwa, au mteja aliyefutwa, hukataliwa kwa 401 na invalid_client. Wigo ambao mteja haruhusiwi kuomba hukataa ubadilishaji wote kwa 400 na invalid_scope; kamwe haupunguzwi kimyakimya.

Mwakilishe mtumiaji mwingine wa Lingara

Programu inayomwakilisha mtumiaji mwingine wa Lingara hutumia ruzuku ya authorization code. Peleka kivinjari cha mtumiaji kwenye URL ya uidhinishaji ukiwa na response_type=code, client_id, redirect_uri inayolingana kabisa na mojawapo uliyosajili, scope, state na code_challenge ya S256. Mtumiaji huona ukurasa wa idhini wa Lingara na kurudi kwenye redirect_uri yako akiwa na code, state na iss. Hakikisha kwamba state ndiyo uliyotuma na kwamba iss ni https://api.getlingara.com kabla ya kutumia msimbo.

PKCE inahitajika

Kila mteja hutumia PKCE, kwa mbinu ya S256 pekee. Tengeneza code_verifier ya nasibu, tuma hash yake ya SHA-256, iliyosimbwa kwa base64url, kama code_challenge pamoja na code_challenge_method=S256, na uhifadhi verifier kwa ajili ya ubadilishaji. Ombi lisilo na mbinu, au lenye plain, hukataliwa kwa invalid_request.

Badilisha msimbo

Ndani ya sekunde 60, tuma kwa POST kwenye sehemu ya mwisho ya tokeni ukiwa na grant_type=authorization_code, code, redirect_uri ileile na code_verifier, ukijithibitisha kama mteja; mteja wa umma hutuma client_id pekee. Jibu huongeza refresh_token, inayoanza na lgr_rt_. Msimbo huanza na lgr_ac_ na hufanya kazi mara moja tu: matumizi ya pili hukataliwa kwa invalid_grant na hukomesha tokeni ambazo ubadilishaji wa kwanza ulitoa.

Onyesha upya

Tokeni ya ufikiaji inapoisha muda, tuma kwa POST kwenye sehemu ya mwisho ya tokeni ukiwa na grant_type=refresh_token na refresh_token, ukijithibitisha tena kama mteja. Kila uonyeshaji upya hurudisha tokeni mpya ya kuonyesha upya: hifadhi ile mpya zaidi pekee. Fanya uonyeshaji upya mmoja baada ya mwingine: tokeni ya zamani ya kuonyesha upya inayotumika zaidi ya sekunde 60 baada ya kubadilishwa huchukuliwa kuwa imeibiwa, na hukomesha tokeni za usakinishaji huo kwa invalid_grant. Tokeni ya kuonyesha upya isiyotumika kwa siku 30 huisha muda. Sehemu ya mwisho ya tokeni huweka kikomo cha maombi kwa kila anwani, kwa hivyo onyesha upya tu tokeni inapoisha muda.

Programu asilia ni wateja wa umma

Programu ya kompyuta ya mezani, ya simu au ya mstari wa amri haiwezi kutunza siri, kwa hivyo ni mteja wa umma: haina siri, hutuma client_id pekee kwenye sehemu ya mwisho ya tokeni, na husajili uelekezaji upya wa loopback kama http://127.0.0.1/callback (mlango wowote) au mpango wa matumizi binafsi kama com.example.app:/callback. Mtumiaji huona ukurasa wa idhini kila mara. Ukurasa wa wavuti hauwezi kuwa mteja: wala sehemu ya mwisho ya tokeni wala /v1/ haijibu preflight ya cross-origin.

Mtumiaji anapoondoa programu yako

Mtumiaji anaweza kuondoa programu yako wakati wowote katika Programu Zilizounganishwa, au kwa kuifuta ikiwa aliisakinisha, na ombi lake linalofuata hushindwa kwa 401. Mtumiaji anapotoka kwenye programu yako, batilisha tokeni yake ya kuonyesha upya kwenye sehemu ya mwisho ya ubatilishaji, jambo ambalo hukomesha tokeni za usakinishaji huo.

Tokeni inapoisha muda

Baada ya saa moja, /v1/ hujibu 401 pamoja na msimbo unauthorized na hitilafu inayoanza na invalid_token. Badilisha tena ombi linapopata 401, au muda mfupi kabla expires_in haujaisha, na ujaribu ombi tena mara moja. Ikiwa ubadilishaji wenyewe utashindwa kwa invalid_client au invalid_scope, mteja au siri yake imefutwa, imebatilishwa au imepunguzwa: acha na urekebishe kwenye ukurasa wa Miunganisho, kwa sababu kujaribu tena hakuwezi kufaulu. Hifadhi tokeni kati ya maombi: sehemu ya mwisho ya tokeni huweka kikomo cha ubadilishaji kwa kila mteja na kila anwani, na programu inayobadilisha kwa kila ombi hukataliwa kwa 429 na rate_limited ndani ya saa hiyo (subiri Retry-After). Ruzuku hii haina tokeni ya kuonyesha upya: siri hubadilishwa tena.

Tokeni za ufikiaji hufikia njia za API pekee

Tokeni ya ufikiaji hufanya kazi tu kwenye njia zilizo chini ya /v1/. Ikitumwa kwa njia nyingine yoyote ya Lingara, hukataliwa kwa 401, na mwili wa jibu huanza na api_token_not_accepted, kama maandishi ya kawaida au ndani ya sehemu ya error, kamwe si katika bahasha ya {code, error} ambayo njia za /v1/ hutumia. Tuma tokeni ya ufikiaji katika kichwa cha Authorization, kama ilivyo hapa chini.

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

Wigo

Kila operesheni inahitaji wigo mmoja hasa, uliotajwa kwenye ukurasa wake. Tokeni ya ufikiaji isiyo na wigo huo hukataliwa kwa 403 na msimbo insufficient_scope. Ili kuita operesheni, omba wigo wake wakati wa ubadilishaji, ikiwa mteja anaruhusiwa kuwa nao. Jedwali lililo hapa chini linaorodhesha kila wigo na operesheni unazoruhusu.

Nani analipia ombi

Mteja hutozwa kwa mojawapo ya njia mbili, inayochaguliwa anapoundwa. Mteja wa allowance hutumia kiwango cha matumizi cha mmiliki wake, kiwango kilekile cha programu zako, na tokeni zake za ufikiaji hukitumia pia; GET /v1/usage huonyesha kilichobaki. Mteja wa metered hatumii kiwango chochote: hutozwa kwa kila krediti kupitia usajili wa utozaji kwa matumizi unaouweka kwenye ukurasa wa Miunganisho. Simu zake hukataliwa kwa 402 na spend_cap_reached mara mteja au akaunti yako inapofikia kikomo chake cha matumizi ya pesa cha kila mwezi, na kwa 402 na metered_billing_inactive wakati utozaji kwa matumizi haujawashwa. Mpango mmoja wa somo ni krediti 10, zamu moja ya mkufunzi krediti 1 na utengenezaji mmoja wa msamiati krediti 3, kwa hivyo units ambazo GET /v1/usage huripoti hubadilishwa kuwa krediti kwa uzito huo. Ombi ambalo programu hufanya kwa niaba ya mtumiaji mwingine, kwa tokeni kutoka kwa msimbo wa uidhinishaji, daima hutumia kiwango cha matumizi cha mtumiaji huyo, bila kujali hali ya mteja.

Weka siri na tokeni kwenye seva

Siri ya mteja inapaswa kukaa kwenye seva unayoidhibiti, kamwe si kwenye ukurasa wa wavuti, kiendelezi cha kivinjari au kifurushi cha programu, ambapo mtu yeyote anaweza kuisoma. Programu asilia ni mteja wa umma na haishikilii siri. Wala /v1/ wala sehemu ya mwisho ya tokeni haijibu preflight ya cross-origin, kwa hivyo kivinjari kwenye tovuti nyingine hakiwezi kuziita hata hivyo.

Dhibiti wateja

Kwenye ukurasa wa Miunganisho, katika app.getlingara.com/admin, unda, badilisha jina na futa wateja, badilisha kile ambacho kila mmoja anaweza kufanya na toleo alilofungwa, na unda na ubatilishe siri zake. Kufuta mteja husimamisha mara moja kila tokeni ya ufikiaji anayoshikilia, na hukomesha idhini ambayo kila mtumiaji amempa. Kubatilisha siri husimamisha, mara moja, kila tokeni ya ufikiaji iliyopatikana kwa kubadilisha siri hiyo. Kupunguza wigo wa mteja pia hutumika mara moja; kuupanua, au kubadilisha toleo lake, hutumika kuanzia ubadilishaji unaofuata.

Zungusha siri

Mteja anaweza kuwa na siri mbili kwa wakati mmoja. Ili kuzungusha, unda siri mpya, isambaze, kisha ubatilishe ile ya zamani tarehe yake ya Ilitumika mwisho kwenye ukurasa wa Miunganisho ikiacha kubadilika. Mchakato ambao tayari una siri mpya lakini bado unashikilia tokeni kutoka kwa ile ya zamani hupata 401 moja na hubadilisha tena. Siri pekee ya mteja haiwezi kubatilishwa: unda mbadala wake kwanza, au futa mteja.

Ikiwa tafsiri na marejeleo ya Kiingereza yanatofautiana, marejeleo ya Kiingereza ndiyo sahihi.