Verifikasie

API-weergawe 2026-10-affable-towhee

Elke oproep na die Lingara API dra 'n toegangtoken. 'n Bediener kry een deur 'n OAuth-kliënt se ID en geheim by die token-eindpunt in te ruil: OAuth 2.0 se client credentials-toekenning, vir 'n bediener wat namens homself optree. Skep kliënte op die Integrasies-bladsy van die Lingara-webtoep, by app.getlingara.com/admin.

'n Sessie of 'n kliënt

Die Lingara-toepassings meld jou aan met 'n sessie, wat elke omvang het en jou plan se toelae gebruik. 'n Kliënt is nouer: jy kies die omvange wat dit toegelaat word wanneer jy dit skep, en elke toegangtoken wat dit kry, dra slegs die omvange waarvoor dit vra.

Drie waardes

Die kliënt-ID begin met lgr_cid_ en benoem die kliënt by die token-eindpunt. Dit is nie 'n geheim nie.

Die kliëntgeheim begin met lgr_cs_ en word slegs na die token-eindpunt gestuur. Dit word een keer gewys, wanneer jy dit skep: kopieer dit dan, want Lingara stoor slegs 'n hash daarvan.

Die toegangtoken begin met lgr_at_ en hou een uur. Dit gaan in die Authorization: Bearer-kopskrif van oproepe onder /v1/, en nêrens anders nie. Dit is die enigste waarde wat in daardie kopskrif hoort: 'n kliëntgeheim wat daar gestuur word, word met 401 geweier.

Kry 'n toegangtoken

Stuur 'n vorm met POST na die token-eindpunt met grant_type=client_credentials. Stuur die kliënt-ID en geheim óf met HTTP Basic-verifikasie óf as die vormvelde client_id en client_secret, nooit albei nie. scope is 'n spasiegeskeide lys van omvange wat die kliënt toegelaat word; laat dit weg om elke omvang te kry wat die kliënt toegelaat word. Die opdrag hieronder vra slegs vir usage:read, die omvang wat die GET /v1/usage-voorbeeld verderaan benodig.

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"

Die antwoord bevat access_token, token_type (Bearer), expires_in (3600, in sekondes) en scope, die omvange wat die token werklik het. 'n Mislukte inruiling antwoord in die OAuth-foutvorm, {error, error_description}, nie in die {code, error}-omhulsel van /v1/ nie. 'n Verkeerde of herroepte geheim, of 'n geskrapte kliënt, word met 401 en invalid_client geweier. 'n Omvang wat die kliënt nie mag aanvra nie, weier die hele inruiling met 400 en invalid_scope; dit word nooit stilweg vernou nie.

Tree op namens 'n ander Lingara-gebruiker

'n Toepassing wat namens 'n ander Lingara-gebruiker optree, gebruik die authorization code-toekenning. Stuur die gebruiker se blaaier na die magtigings-URL met response_type=code, client_id, 'n redirect_uri wat presies ooreenstem met een wat jy geregistreer het, scope, state en 'n code_challenge met S256. Die gebruiker sien Lingara se toestemmingsbladsy en keer terug na jou redirect_uri met code, state en iss. Kontroleer dat state die een is wat jy gestuur het en dat iss gelyk is aan https://api.getlingara.com voordat jy die kode gebruik.

PKCE is verpligtend

Elke kliënt gebruik PKCE, slegs met die S256-metode. Maak 'n ewekansige code_verifier, stuur sy SHA-256-hash, base64url-geënkodeer, as code_challenge met code_challenge_method=S256, en hou die verifieerder vir die inruiling. 'n Versoek sonder 'n metode, of met plain, word met invalid_request geweier.

Ruil die kode in

Stuur binne 60 sekondes met POST na die token-eindpunt met grant_type=authorization_code, code, dieselfde redirect_uri en code_verifier, en verifieer as die kliënt; 'n openbare kliënt stuur slegs client_id. Die antwoord voeg 'n refresh_token by, wat met lgr_rt_ begin. Die kode begin met lgr_ac_ en werk een keer: 'n tweede gebruik word met invalid_grant geweier en beëindig die tokens wat die eerste inruiling uitgereik het.

Herlaai

Wanneer die toegangtoken verval, stuur met POST na die token-eindpunt met grant_type=refresh_token en die refresh_token, en verifieer weer as die kliënt. Elke herlaai gee 'n nuwe herlaaitoken terug: hou slegs die nuutste. Doen jou herlaaie een ná die ander: 'n ou herlaaitoken wat meer as 60 sekondes nadat dit vervang is, gebruik word, word as gesteel beskou en beëindig daardie installasie se tokens met invalid_grant. 'n Herlaaitoken wat 30 dae lank nie gebruik word nie, verval. Die token-eindpunt beperk versoeke per adres, so herlaai slegs wanneer 'n token verval het.

Inheemse toepassings is openbare kliënte

'n Rekenaar-, mobiele of opdragreëltoepassing kan nie 'n geheim bewaar nie, so dit is 'n openbare kliënt: dit het geen geheim nie, stuur slegs client_id na die token-eindpunt, en registreer 'n loopback-herleiding soos http://127.0.0.1/callback (enige poort) of 'n skema vir privaat gebruik soos com.example.app:/callback. Die gebruiker sien elke keer die toestemmingsbladsy. 'n Webblad kan nie 'n kliënt wees nie: nóg die token-eindpunt nóg /v1/ beantwoord 'n kruisoorsprong-preflight.

Wanneer die gebruiker jou toepassing verwyder

Die gebruiker kan jou toepassing enige tyd onder Gekoppelde toepassings verwyder, of deur dit te deïnstalleer as hulle dit geïnstalleer het, en die toepassing se volgende oproep misluk dan met 401. Wanneer die gebruiker by jou toepassing afmeld, herroep die toepassing se herlaaitoken by die herroepingseindpunt, wat daardie installasie se tokens beëindig.

Wanneer die token verval

Ná 'n uur antwoord /v1/ met 401, die kode unauthorized en 'n fout wat met invalid_token begin. Ruil weer in wanneer 'n oproep 401 kry, of kort voordat expires_in verstryk, en probeer die oproep een keer weer. As die inruiling self met invalid_client of invalid_scope misluk, is die kliënt of sy geheim geskrap, herroep of vernou: hou op en maak dit reg op die Integrasies-bladsy, want weer probeer kan nie slaag nie. Hou die token tussen oproepe: die token-eindpunt beperk inruilings per kliënt en per adres, en 'n program wat by elke oproep inruil, word binne die uur met 429 en rate_limited geweier (wag vir Retry-After). Hierdie toekenning het geen herlaaitoken nie: die geheim word weer ingeruil.

Toegangtokens bereik slegs die API-roetes

'n Toegangtoken werk slegs op roetes onder /v1/. As dit na enige ander Lingara-roete gestuur word, word dit met 401 geweier, en die liggaam begin met api_token_not_accepted, as gewone teks of binne 'n error-veld, nooit in die {code, error}-omhulsel wat die /v1/-roetes gebruik nie. Stuur die toegangtoken in die Authorization-kopskrif, soos hieronder.

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

Omvange

Elke operasie benodig presies een omvang, wat op sy bladsy genoem word. 'n Toegangtoken sonder daardie omvang word met 403 en die kode insufficient_scope geweier. Om die operasie op te roep, vra vir sy omvang by die inruiling, as die kliënt dit toegelaat word. Die tabel hieronder lys elke omvang en die operasies wat dit toelaat.

Wie betaal vir 'n oproep

'n Kliënt word op een van twee maniere gefaktureer, gekies wanneer dit geskep word. 'n allowance-kliënt gebruik sy eienaar se toelae, dieselfde toelae as jou toepassings, en sy toegangtokens gebruik dit ook; GET /v1/usage wys wat oor is. 'n metered-kliënt gebruik geen toelae nie: dit word per krediet gefaktureer deur 'n gebruiksfaktureringsintekening wat jy op die Integrasies-bladsy opstel. Sy oproepe word met 402 en spend_cap_reached geweier sodra die kliënt of jou rekening sy maandelikse bestedingslimiet bereik, en met 402 en metered_billing_inactive solank gebruiksfakturering nie aktief is nie. 'n Lesplan is 10 krediete, 'n tutorbeurt 1 krediet en 'n woordeskatgenerering 3 krediete, so die units wat GET /v1/usage rapporteer, word teen daardie gewigte na krediete omgeskakel. 'n Oproep wat 'n toepassing namens 'n ander gebruiker maak, met 'n token uit 'n magtigingskode, gebruik altyd daardie gebruiker se toelae, ongeag die kliënt se modus.

Hou geheime en tokens op 'n bediener

Die kliëntgeheim hoort op 'n bediener wat jy beheer, nooit in 'n webblad, 'n blaaieruitbreiding of 'n toepassingsbundel nie, waar enigiemand dit kan lees. 'n Inheemse toepassing is 'n openbare kliënt en hou geen geheim nie. Nóg /v1/ nóg die token-eindpunt beantwoord 'n kruisoorsprong-preflight, so 'n blaaier op 'n ander webwerf kan hulle in elk geval nie oproep nie.

Bestuur kliënte

Op die Integrasies-bladsy, by app.getlingara.com/admin, kan jy kliënte skep, hernoem en skrap, verander wat elkeen kan doen en aan watter weergawe dit vasgepen is, en sy geheime skep en herroep. Om 'n kliënt te skrap, stop onmiddellik elke toegangtoken wat dit hou, en beëindig die toegang wat elke gebruiker daaraan verleen het. Om 'n geheim te herroep, stop onmiddellik elke toegangtoken waarvoor daardie geheim ingeruil is. Om 'n kliënt se omvange te vernou, geld ook onmiddellik; om hulle te verbreed, of sy weergawe te verander, geld vanaf die volgende inruiling.

Roteer 'n geheim

'n Kliënt kan twee geheime tegelyk hê. Om te roteer, skep 'n nuwe geheim, ontplooi dit, en herroep die ou een sodra sy Laas gebruik-datum op die Integrasies-bladsy ophou verander. 'n Proses wat reeds die nuwe geheim het maar nog 'n token van die ou een hou, kry een 401 en ruil weer in. 'n Kliënt se enigste geheim kan nie herroep word nie: skep eers sy plaasvervanger, of skrap die kliënt.

Indien 'n vertaling en die Engelse verwysing verskil, is die Engelse verwysing korrek.