Pagpapatunay

Bersyon ng API 2026-10-affable-towhee

Bawat tawag sa Lingara API ay may dalang access token. Nakakakuha nito ang isang server sa pamamagitan ng pagpapalit ng ID at secret ng isang OAuth client sa token endpoint: ang client credentials grant ng OAuth 2.0, para sa server na kumikilos para sa sarili nito. Gumawa ng mga client sa pahinang Mga integration ng Lingara web app, sa app.getlingara.com/admin.

Session o client

Pinapa-sign in ka ng mga Lingara app gamit ang isang session, na may hawak ng bawat scope at gumagamit ng allowance ng iyong plan. Mas makitid ang client: pinipili mo ang mga scope na pinapayagan dito kapag ginawa mo ito, at ang bawat access token na nakukuha nito ay may dala lamang ng mga scope na hinihingi nito.

Tatlong value

Nagsisimula ang ID ng client sa lgr_cid_ at pinapangalanan nito ang client sa token endpoint. Hindi ito lihim.

Nagsisimula ang secret ng client sa lgr_cs_ at ipinapadala lamang ito sa token endpoint. Isang beses lamang ito ipinapakita, kapag ginawa mo ito: kopyahin ito agad, dahil hash lamang nito ang iniimbak ng Lingara.

Nagsisimula ang access token sa lgr_at_ at tumatagal ito nang isang oras. Inilalagay ito sa Authorization: Bearer header ng mga tawag sa ilalim ng /v1/, at wala nang iba pang lugar. Ito lamang ang value na nararapat sa header na iyon: ang secret ng client na ipinadala roon ay tinatanggihan nang may 401.

Kumuha ng access token

Magpadala ng form gamit ang POST sa token endpoint na may grant_type=client_credentials. Ipadala ang ID ng client at ang secret gamit ang HTTP Basic authentication o bilang mga form field na client_id at client_secret, hindi kailanman pareho. Ang scope ay listahan, na pinaghihiwalay ng espasyo, ng mga scope na pinapayagan sa client; alisin ito para makuha ang bawat scope na pinapayagan sa client. Humihingi lamang ang command sa ibaba ng usage:read, ang scope na kailangan ng halimbawang GET /v1/usage sa bandang ibaba.

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"

Dala ng response ang access_token, token_type (Bearer), expires_in (3600, sa segundo) at scope, ang mga scope na talagang hawak ng token. Ang nabigong pagpapalit ay sumasagot sa anyo ng OAuth error, {error, error_description}, hindi sa {code, error} envelope ng /v1/. Ang mali o binawing secret, o binurang client, ay tinatanggihan nang may 401 at invalid_client. Ang scope na hindi maaaring hingin ng client ay nagpapabigo sa buong pagpapalit nang may 400 at invalid_scope; hindi ito kailanman tahimik na pinakikitid.

Kumilos para sa ibang user ng Lingara

Ginagamit ng app na kumikilos para sa ibang user ng Lingara ang authorization code grant. Ipadala ang browser ng user sa authorization URL na may response_type=code, client_id, isang redirect_uri na eksaktong tumutugma sa isang inirehistro mo, scope, state at isang S256 na code_challenge. Makikita ng user ang pahina ng pahintulot ng Lingara at babalik sa iyong redirect_uri na may code, state at iss. Tiyaking ang state ay ang ipinadala mo at ang iss ay https://api.getlingara.com bago mo gamitin ang code.

Kinakailangan ang PKCE

Gumagamit ng PKCE ang bawat client, gamit lamang ang paraang S256. Gumawa ng random na code_verifier, ipadala ang SHA-256 hash nito, naka-encode sa base64url, bilang code_challenge na may code_challenge_method=S256, at itago ang verifier para sa pagpapalit. Ang request na walang paraan, o may plain, ay tinatanggihan nang may invalid_request.

Ipalit ang code

Sa loob ng 60 segundo, mag-POST sa token endpoint na may grant_type=authorization_code, code, ang parehong redirect_uri at code_verifier, na nagpapatunay bilang client; ang public client ay nagpapadala lamang ng client_id. Nagdaragdag ang response ng refresh_token, na nagsisimula sa lgr_rt_. Nagsisimula ang code sa lgr_ac_ at gumagana nang isang beses lamang: ang ikalawang paggamit ay tinatanggihan nang may invalid_grant at tinatapos ang mga token na inilabas ng unang pagpapalit.

Mag-refresh

Kapag nag-expire ang access token, mag-POST sa token endpoint na may grant_type=refresh_token at ang refresh_token, na muling nagpapatunay bilang client. Bawat refresh ay nagbabalik ng bagong refresh token: itago lamang ang pinakabago. Pagsunud-sunurin ang iyong mga refresh: ang lumang refresh token na ginamit nang higit sa 60 segundo matapos itong mapalitan ay itinuturing na ninakaw, at tinatapos nito ang mga token ng install na iyon nang may invalid_grant. Nag-e-expire ang refresh token na hindi nagamit nang 30 araw. Nililimitahan ng token endpoint ang mga request bawat address, kaya mag-refresh lamang kapag naubos na ang isang token.

Mga public client ang mga native app

Hindi makapagtatago ng secret ang desktop, mobile o command-line app, kaya ito ay public client: wala itong secret, nagpapadala lamang ng client_id sa token endpoint, at nagrerehistro ng loopback redirect gaya ng http://127.0.0.1/callback (anumang port) o ng private-use scheme gaya ng com.example.app:/callback. Makikita ng user ang pahina ng pahintulot sa bawat pagkakataon. Hindi maaaring maging client ang web page: hindi sumasagot ang token endpoint o ang /v1/ sa anumang cross-origin preflight.

Kapag inalis ng user ang iyong app

Maaaring alisin ng user ang iyong app anumang oras sa Mga nakakonektang app, o sa pag-uninstall nito kung siya ang nag-install nito, at mabibigo ang susunod na tawag nito nang may 401. Kapag nag-sign out ang user sa iyong app, bawiin ang refresh token nito sa revocation endpoint, na tumatapos sa mga token ng install na iyon.

Kapag nag-expire ang token

Pagkalipas ng isang oras, sumasagot ang /v1/ ng 401 na may code na unauthorized at error na nagsisimula sa invalid_token. Magpalit muli kapag nakakuha ang isang tawag ng 401, o bago maubos ang expires_in, at subukang muli ang tawag nang isang beses. Kung ang pagpapalit mismo ay nabigo nang may invalid_client o invalid_scope, ang client o ang secret nito ay binura, binawi o pinakitid: huminto at ayusin ito sa pahinang Mga integration, dahil hindi magtatagumpay ang muling pagsubok. Itago ang token sa pagitan ng mga tawag: nililimitahan ng token endpoint ang mga pagpapalit bawat client at bawat address, at ang programang nagpapalit sa bawat tawag ay tinatanggihan nang may 429 at rate_limited sa loob ng isang oras (hintayin ang Retry-After). Walang refresh token ang grant na ito: muling ipinapalit ang secret.

Mga API ruta lamang ang naaabot ng access token

Gumagana lamang ang access token sa mga rutang nasa ilalim ng /v1/. Kapag ipinadala sa ibang Lingara ruta, tinatanggihan ito nang may 401, at nagsisimula ang body sa api_token_not_accepted, bilang plain text o sa loob ng field na error, hindi kailanman sa {code, error} envelope na ginagamit ng mga /v1/ na ruta. Ipadala ang access token sa Authorization header, gaya ng nasa ibaba.

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

Mga scope

Bawat operasyon ay nangangailangan ng eksaktong isang scope, na nakapangalan sa pahina nito. Ang access token na walang scope na iyon ay tinatanggihan nang may 403 at code na insufficient_scope. Para matawag ang operasyon, hingin ang scope nito sa pagpapalit, kung pinapayagan ito sa client. Inililista ng talahanayan sa ibaba ang bawat scope at ang mga operasyong pinapahintulutan nito.

Sino ang nagbabayad para sa isang tawag

Sinisingil ang isang client sa isa sa dalawang paraan, na pinipili kapag ginawa ito. Ang isang allowance client ay gumagamit ng allowance ng may-ari nito, ang parehong allowance ng iyong mga app, at gumagamit din nito ang mga access token nito; ipinapakita ng GET /v1/usage kung ano ang natitira. Ang isang metered client ay hindi gumagamit ng allowance: sinisingil ito kada credit sa pamamagitan ng usage-billing subscription na ise-set up mo sa pahinang Mga integration. Tinatanggihan ang mga tawag nito gamit ang 402 at spend_cap_reached kapag naabot na ng client o ng iyong account ang buwanang limitasyon sa paggastos, at gamit ang 402 at metered_billing_inactive habang hindi aktibo ang usage billing. Ang isang lesson plan ay 10 credit, ang isang turn ng tutor ay 1 credit at ang isang pagbuo ng bokabularyo ay 3 credit, kaya ang units na iniuulat ng GET /v1/usage ay nako-convert sa credit gamit ang mga bigat na iyon. Ang tawag na ginagawa ng isang app para sa ibang user, gamit ang token mula sa authorization code, ay laging gumagamit ng allowance ng user na iyon, anuman ang mode ng client.

Itago ang mga secret at token sa server

Ang secret ng client ay dapat nasa server na kontrolado mo, hindi kailanman sa web page, browser extension o app bundle, kung saan mababasa ito ng kahit sino. Ang native app ay public client at walang hawak na secret. Hindi sumasagot ang /v1/ o ang token endpoint sa anumang cross-origin preflight, kaya hindi rin sila matatawag ng browser sa ibang site.

Pamahalaan ang mga client

Sa pahinang Mga integration, sa app.getlingara.com/admin, gumawa, palitan ang pangalan at burahin ang mga client, baguhin ang kayang gawin ng bawat isa at kung saang bersyon ito nakakabit, at gumawa at bawiin ang mga secret nito. Ang pagbura sa client ay agad na nagpapatigil sa bawat access token na hawak nito, at tinatapos ang pahintulot ng bawat user dito. Ang pagbawi sa secret ay agad na nagpapatigil sa bawat access token na nakuha kapalit ng secret na iyon. Agad ding umiiral ang pagpapakitid sa mga scope ng client; ang pagpapalawak sa mga ito, o ang pagpapalit ng bersyon nito, ay umiiral simula sa susunod na pagpapalit.

Palitan ang secret

Maaaring humawak ang isang client ng dalawang secret nang sabay. Para palitan ito, gumawa ng bagong secret, i-deploy ito, at bawiin ang luma kapag hindi na nagbabago ang petsa ng Huling ginamit nito sa pahinang Mga integration. Ang prosesong may bagong secret na pero may hawak pang token mula sa luma ay makakakuha ng isang 401 at magpapalit muli. Hindi maaaring bawiin ang nag-iisang secret ng client: gawin muna ang kapalit nito, o burahin ang client.

Kung magkaiba ang isang salin at ang sangguniang Ingles, ang sangguniang Ingles ang tama.