Todennus

API-versio 2026-10-affable-towhee

Jokainen Lingara API -kutsu sisältää käyttöoikeustunnuksen. Palvelin saa sellaisen vaihtamalla OAuth-asiakkaan asiakastunnisteen ja salaisuuden tunnuspäätepisteessä: kyseessä on OAuth 2.0:n client credentials -myöntö palvelimelle, joka toimii omissa nimissään. Luo asiakkaita Lingara-verkkosovelluksen Integraatiot-sivulla osoitteessa app.getlingara.com/admin.

Istunto vai asiakas

Lingara-sovellukset kirjaavat sinut sisään istunnolla, jolla on kaikki oikeuslaajuudet ja joka kuluttaa tilauksesi kiintiötä. Asiakas on suppeampi: valitset sille sallitut oikeuslaajuudet, kun luot sen, ja jokaisessa sen saamassa käyttöoikeustunnuksessa on vain ne oikeuslaajuudet, joita se pyytää.

Kolme arvoa

Asiakastunniste alkaa lgr_cid_ ja nimeää asiakkaan tunnuspäätepisteessä. Se ei ole salaisuus.

Asiakkaan salaisuus alkaa lgr_cs_, ja se lähetetään vain tunnuspäätepisteeseen. Se näytetään vain kerran, kun luot sen: kopioi se silloin, sillä Lingara tallentaa siitä vain tiivisteen.

Käyttöoikeustunnus alkaa lgr_at_ ja on voimassa tunnin. Se lähetetään polun /v1/ alaisten kutsujen Authorization: Bearer -otsakkeessa eikä missään muualla. Se on ainoa arvo, joka kuuluu tuohon otsakkeeseen: sinne lähetetty asiakkaan salaisuus hylätään tilakoodilla 401.

Hanki käyttöoikeustunnus

Lähetä lomake POST-pyyntönä tunnuspäätepisteeseen arvolla grant_type=client_credentials. Lähetä asiakastunniste ja salaisuus joko HTTP Basic -todennuksella tai lomakekenttinä client_id ja client_secret, ei koskaan molemmilla tavoilla. scope on välilyönnein eroteltu luettelo asiakkaalle sallituista oikeuslaajuuksista; jätä se pois, niin saat kaikki asiakkaalle sallitut oikeuslaajuudet. Alla oleva komento pyytää pelkkää oikeuslaajuutta usage:read, jota jäljempänä oleva GET /v1/usage -esimerkki tarvitsee.

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"

Vastauksessa on access_token, token_type (Bearer), expires_in (3600, sekunteina) ja scope eli oikeuslaajuudet, jotka tunnuksella todella on. Epäonnistunut vaihto vastaa OAuthin virhemuodossa {error, error_description}, ei polun /v1/ {code, error}-kehyksessä. Väärä tai peruutettu salaisuus tai poistettu asiakas hylätään tilakoodilla 401 ja koodilla invalid_client. Oikeuslaajuus, jota asiakas ei saa pyytää, hylkää koko vaihdon tilakoodilla 400 ja koodilla invalid_scope; pyyntöä ei koskaan kavenneta hiljaisesti.

Toimi toisen Lingara-käyttäjän puolesta

Toisen Lingara-käyttäjän puolesta toimiva sovellus käyttää valtuutuskoodimyöntöä. Ohjaa käyttäjän selain valtuutus-URL-osoitteeseen parametreilla response_type=code, client_id, redirect_uri, joka vastaa täsmälleen yhtä rekisteröimääsi osoitetta, scope, state sekä S256-menetelmällä laskettu code_challenge. Käyttäjä näkee Lingaran suostumussivun ja palaa osoitteeseesi redirect_uri parametrien code, state ja iss kanssa. Tarkista ennen koodin käyttämistä, että state on lähettämäsi arvo ja että iss on https://api.getlingara.com.

PKCE on pakollinen

Jokainen asiakas käyttää PKCE:tä ja vain menetelmää S256. Luo satunnainen code_verifier, lähetä sen SHA-256-tiiviste base64url-koodattuna arvona code_challenge yhdessä parametrin code_challenge_method=S256 kanssa ja säilytä tarkiste vaihtoa varten. Pyyntö ilman menetelmää tai menetelmällä plain hylätään koodilla invalid_request.

Vaihda koodi

Lähetä 60 sekunnin kuluessa POST-pyyntö tunnuspäätepisteeseen arvoilla grant_type=authorization_code, code, sama redirect_uri ja code_verifier todentautuen asiakkaana; julkinen asiakas lähettää pelkän client_id-arvon. Vastaukseen lisätään refresh_token, joka alkaa lgr_rt_. Koodi alkaa lgr_ac_ ja toimii kerran: toinen käyttö hylätään koodilla invalid_grant, ja se mitätöi ensimmäisessä vaihdossa myönnetyt tunnukset.

Päivitä

Kun käyttöoikeustunnus vanhenee, lähetä POST-pyyntö tunnuspäätepisteeseen arvoilla grant_type=refresh_token ja refresh_token todentautuen jälleen asiakkaana. Jokainen päivitys palauttaa uuden päivitystunnuksen: säilytä vain uusin. Tee päivitykset peräkkäin: vanha päivitystunnus, jota käytetään yli 60 sekuntia sen korvaamisen jälkeen, katsotaan varastetuksi, ja se mitätöi kyseisen asennuksen tunnukset koodilla invalid_grant. Päivitystunnus, jota ei ole käytetty 30 päivään, vanhenee. Tunnuspäätepiste rajoittaa pyyntöjä osoitetta kohden, joten päivitä vain, kun tunnus on vanhentunut.

Natiivisovellukset ovat julkisia asiakkaita

Työpöytä-, mobiili- tai komentorivisovellus ei voi pitää salaisuutta, joten se on julkinen asiakas: sillä ei ole salaisuutta, se lähettää tunnuspäätepisteeseen pelkän client_id-arvon ja rekisteröi loopback-uudelleenohjauksen, kuten http://127.0.0.1/callback (mikä tahansa portti), tai yksityiskäyttöisen skeeman, kuten com.example.app:/callback. Käyttäjä näkee suostumussivun joka kerta. Verkkosivu ei voi olla asiakas: kumpikaan, tunnuspäätepiste tai /v1/, ei vastaa cross-origin-esitarkistuksiin (preflight).

Kun käyttäjä poistaa sovelluksesi

Käyttäjä voi poistaa sovelluksesi milloin tahansa Yhdistetyt sovellukset -sivulla tai poistamalla sen asennuksen, jos hän on asentanut sen, ja sen seuraava kutsu epäonnistuu tilakoodilla 401. Kun käyttäjä kirjautuu ulos sovelluksestasi, peruuta sen päivitystunnus peruutuspäätepisteessä, mikä mitätöi kyseisen asennuksen tunnukset.

Kun tunnus vanhenee

Tunnin kuluttua /v1/ vastaa tilakoodilla 401, koodilla unauthorized ja virheellä, joka alkaa invalid_token. Vaihda uudelleen, kun kutsu saa tilakoodin 401 tai vähän ennen kuin expires_in umpeutuu, ja yritä kutsua kerran uudelleen. Jos itse vaihto epäonnistuu koodilla invalid_client tai invalid_scope, asiakas tai sen salaisuus on poistettu tai peruutettu tai sen oikeuslaajuuksia on kavennettu: lopeta ja korjaa asia Integraatiot-sivulla, sillä uudelleenyritys ei voi onnistua. Säilytä tunnus kutsujen välillä: tunnuspäätepiste rajoittaa vaihtoja asiakasta ja osoitetta kohden, ja ohjelma, joka vaihtaa jokaisella kutsulla, hylätään tunnin sisällä tilakoodilla 429 ja koodilla rate_limited (odota Retry-After-ajan verran). Tässä myönnössä ei ole päivitystunnusta: salaisuus vaihdetaan uudelleen.

Käyttöoikeustunnukset toimivat vain API-reiteillä

Käyttöoikeustunnus toimii vain reiteillä, jotka ovat polun /v1/ alla. Jos se lähetetään mille tahansa muulle Lingara-reitille, se hylätään tilakoodilla 401, ja runko alkaa api_token_not_accepted, joko pelkkänä tekstinä tai error-kentän sisällä, ei koskaan {code, error}-kehyksessä, jota /v1/-reitit käyttävät. Lähetä käyttöoikeustunnus Authorization-otsakkeessa alla olevan mukaisesti.

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

Oikeuslaajuudet

Jokainen toiminto vaatii täsmälleen yhden oikeuslaajuuden, joka mainitaan toiminnon sivulla. Käyttöoikeustunnus, jolla ei ole tätä oikeuslaajuutta, hylätään tilakoodilla 403 ja koodilla insufficient_scope. Kutsuaksesi toimintoa pyydä sen oikeuslaajuutta vaihdossa, jos se on asiakkaalle sallittu. Alla oleva taulukko luettelee jokaisen oikeuslaajuuden ja sen sallimat toiminnot.

Kuka maksaa kutsun

Asiakas laskutetaan jommallakummalla kahdesta tavasta, joka valitaan asiakasta luotaessa. allowance-asiakas kuluttaa omistajansa kiintiötä, samaa kiintiötä kuin sovelluksesi, ja myös sen käyttöoikeustunnukset kuluttavat sitä; GET /v1/usage näyttää, mitä on jäljellä. metered-asiakas ei kuluta kiintiötä: se laskutetaan krediittien mukaan käytön mukaisen laskutuksen tilauksella, jonka otat käyttöön Integraatiot-sivulla. Sen kutsut hylätään koodeilla 402 ja spend_cap_reached, kun asiakas tai tilisi saavuttaa kuukausittaisen kulutusrajansa, ja koodeilla 402 ja metered_billing_inactive, kun käytön mukainen laskutus ei ole käytössä. Tuntisuunnitelma on 10 krediittiä, tutorin vuoro 1 krediitti ja sanaston luonti 3 krediittiä, joten kutsun GET /v1/usage ilmoittamat units muunnetaan krediiteiksi näillä painoilla. Kutsu, jonka sovellus tekee toisen käyttäjän puolesta valtuutuskoodista saadulla tunnuksella, kuluttaa aina kyseisen käyttäjän kiintiötä asiakkaan tilasta riippumatta.

Pidä salaisuudet ja tunnukset palvelimella

Asiakkaan salaisuus kuuluu hallitsemallesi palvelimelle, ei koskaan verkkosivulle, selainlaajennukseen tai sovelluspakettiin, joista kuka tahansa voi lukea sen. Natiivisovellus on julkinen asiakas, eikä sillä ole salaisuutta. Kumpikaan, /v1/ tai tunnuspäätepiste, ei vastaa cross-origin-esitarkistuksiin (preflight), joten toisella sivustolla oleva selain ei voi kutsua niitä muutenkaan.

Hallitse asiakkaita

Integraatiot-sivulla osoitteessa app.getlingara.com/admin voit luoda, nimetä uudelleen ja poistaa asiakkaita, muuttaa, mitä kukin voi tehdä ja mihin versioon se on kiinnitetty, sekä luoda ja peruuttaa sen salaisuuksia. Asiakkaan poistaminen pysäyttää heti jokaisen sen hallussa olevan käyttöoikeustunnuksen ja päättää jokaisen käyttäjän sille antaman valtuutuksen. Salaisuuden peruuttaminen pysäyttää heti jokaisen käyttöoikeustunnuksen, joka on saatu vaihtamalla tuo salaisuus. Asiakkaan oikeuslaajuuksien kaventaminen tulee myös voimaan heti; niiden laajentaminen tai version vaihtaminen tulee voimaan seuraavasta vaihdosta alkaen.

Kierrätä salaisuus

Asiakkaalla voi olla kaksi salaisuutta kerrallaan. Kierrätä luomalla uusi salaisuus, ottamalla se käyttöön ja peruuttamalla vanha, kun sen Viimeksi käytetty -päiväys Integraatiot-sivulla lakkaa muuttumasta. Prosessi, jolla on jo uusi salaisuus mutta yhä vanhalla saatu tunnus, saa yhden 401-vastauksen ja vaihtaa uudelleen. Asiakkaan ainoaa salaisuutta ei voi peruuttaa: luo ensin sen korvaaja tai poista asiakas.

Jos käännös ja englanninkielinen viite poikkeavat toisistaan, englanninkielinen viite on oikea.