Authenticatie

API-versie 2026-10-affable-towhee

Elke aanroep naar de Lingara API bevat een toegangstoken. Een server krijgt er een door de client-ID en het geheim van een OAuth-client in te ruilen bij het token-endpoint: de client credentials grant van OAuth 2.0, voor een server die namens zichzelf handelt. Maak clients aan op de pagina Integraties van de Lingara-webapp, op app.getlingara.com/admin.

Een sessie of een client

De Lingara-apps melden je aan met een sessie, die elke scope heeft en het tegoed van je abonnement verbruikt. Een client is beperkter: je kiest bij het aanmaken welke scopes hij mag gebruiken, en elk toegangstoken dat hij krijgt, bevat alleen de scopes waar hij om vraagt.

Drie waarden

De client-ID begint met lgr_cid_ en identificeert de client bij het token-endpoint. Hij is niet geheim.

Het clientgeheim begint met lgr_cs_ en wordt alleen naar het token-endpoint gestuurd. Het wordt één keer getoond, wanneer je het aanmaakt: kopieer het dan, want Lingara slaat er alleen een hash van op.

Het toegangstoken begint met lgr_at_ en is één uur geldig. Het hoort in de Authorization: Bearer-header van aanroepen onder /v1/, en nergens anders. Het is de enige waarde die in die header thuishoort: een clientgeheim dat daar wordt gestuurd, wordt geweigerd met 401.

Een toegangstoken krijgen

Stuur met POST een formulier naar het token-endpoint met grant_type=client_credentials. Stuur de client-ID en het geheim mee via HTTP Basic-authenticatie of als de formuliervelden client_id en client_secret, nooit allebei. scope is een door spaties gescheiden lijst van scopes die de client mag gebruiken; laat het weg om elke scope te krijgen die de client mag gebruiken. Het commando hieronder vraagt alleen om usage:read, de scope die het voorbeeld GET /v1/usage verderop nodig heeft.

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"

Het antwoord bevat access_token, token_type (Bearer), expires_in (3600, in seconden) en scope, de scopes die het token werkelijk heeft. Een mislukte inruil antwoordt in de OAuth-foutvorm, {error, error_description}, niet in de {code, error}-envelop van /v1/. Een onjuist of ingetrokken geheim, of een verwijderde client, wordt geweigerd met 401 en invalid_client. Een scope die de client niet mag aanvragen, laat de hele inruil weigeren met 400 en invalid_scope; hij wordt nooit stilzwijgend ingeperkt.

Handelen voor een andere Lingara-gebruiker

Een app die handelt voor een andere Lingara-gebruiker, gebruikt de authorization code grant. Stuur de browser van de gebruiker naar de autorisatie-URL met response_type=code, client_id, een redirect_uri die exact overeenkomt met een die je hebt geregistreerd, scope, state en een code_challenge met S256. De gebruiker ziet de toestemmingspagina van Lingara en keert terug naar je redirect_uri met code, state en iss. Controleer dat state de waarde is die je hebt gestuurd en dat iss gelijk is aan https://api.getlingara.com voordat je de code gebruikt.

PKCE is verplicht

Elke client gebruikt PKCE, uitsluitend met de methode S256. Maak een willekeurige code_verifier, stuur de SHA-256-hash ervan, base64url-gecodeerd, als code_challenge met code_challenge_method=S256, en bewaar de verifier voor de inruil. Een verzoek zonder methode, of met plain, wordt geweigerd met invalid_request.

De code inruilen

Stuur binnen 60 seconden met POST naar het token-endpoint: grant_type=authorization_code, code, dezelfde redirect_uri en code_verifier, en authenticeer je als de client; een publieke client stuurt alleen client_id. Het antwoord bevat daarnaast een refresh_token, dat begint met lgr_rt_. De code begint met lgr_ac_ en werkt één keer: een tweede gebruik wordt geweigerd met invalid_grant en beëindigt de tokens die de eerste inruil heeft uitgegeven.

Vernieuwen

Wanneer het toegangstoken verloopt, stuur je met POST naar het token-endpoint grant_type=refresh_token en het refresh_token, en authenticeer je je opnieuw als de client. Elke vernieuwing levert een nieuw vernieuwingstoken op: bewaar alleen het nieuwste. Voer je vernieuwingen na elkaar uit: een oud vernieuwingstoken dat meer dan 60 seconden na zijn vervanging wordt gebruikt, wordt als gestolen beschouwd en beëindigt de tokens van die installatie met invalid_grant. Een vernieuwingstoken dat 30 dagen niet wordt gebruikt, verloopt. Het token-endpoint beperkt verzoeken per adres, dus vernieuw alleen wanneer een token is verlopen.

Native apps zijn publieke clients

Een desktop-, mobiele of opdrachtregel-app kan geen geheim bewaren en is dus een publieke client: hij heeft geen geheim, stuurt alleen client_id naar het token-endpoint en registreert een loopback-redirect zoals http://127.0.0.1/callback (elke poort) of een schema voor privégebruik zoals com.example.app:/callback. De gebruiker ziet de toestemmingspagina elke keer. Een webpagina kan geen client zijn: noch het token-endpoint noch /v1/ beantwoordt een cross-origin preflight.

Wanneer de gebruiker je app verwijdert

De gebruiker kan je app op elk moment verwijderen onder Verbonden apps, of door de app te deïnstalleren als hij die zelf heeft geïnstalleerd; de volgende aanroep van de app mislukt dan met 401. Wanneer de gebruiker zich afmeldt bij je app, trek je het vernieuwingstoken van de app in bij het intrekkings-endpoint, wat de tokens van die installatie beëindigt.

Wanneer het token verloopt

Na een uur antwoordt /v1/ met 401, de code unauthorized en een fout die begint met invalid_token. Ruil opnieuw in wanneer een aanroep 401 krijgt, of kort voordat expires_in afloopt, en probeer de aanroep één keer opnieuw. Mislukt de inruil zelf met invalid_client of invalid_scope, dan is de client of zijn geheim verwijderd, ingetrokken of ingeperkt: stop en los het op op de pagina Integraties, want opnieuw proberen kan niet slagen. Bewaar het token tussen aanroepen: het token-endpoint beperkt inruilen per client en per adres, en een programma dat bij elke aanroep inruilt, wordt binnen het uur geweigerd met 429 en rate_limited (wacht op Retry-After). Deze grant heeft geen vernieuwingstoken: het geheim wordt opnieuw ingeruild.

Toegangstokens bereiken alleen de API-routes

Een toegangstoken werkt alleen op routes onder /v1/. Naar een andere Lingara-route gestuurd, wordt het geweigerd met 401 en begint de body met api_token_not_accepted, als platte tekst of in een error-veld, nooit in de {code, error}-envelop die de /v1/-routes gebruiken. Stuur het toegangstoken in de Authorization-header, zoals hieronder.

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

Scopes

Elke bewerking vereist precies één scope, vermeld op de pagina van die bewerking. Een toegangstoken zonder die scope wordt geweigerd met 403 en de code insufficient_scope. Vraag bij de inruil om de scope van de bewerking om die aan te roepen, als de client die scope mag gebruiken. De tabel hieronder toont elke scope en de bewerkingen die hij toestaat.

Wie betaalt voor een aanroep

Een client wordt op een van twee manieren afgerekend, gekozen bij het aanmaken. Een allowance-client verbruikt het tegoed van zijn eigenaar, hetzelfde tegoed als je apps, en zijn toegangstokens verbruiken het ook; GET /v1/usage toont wat er over is. Een metered-client verbruikt geen tegoed: hij wordt per credit afgerekend via een abonnement met verbruiksafrekening dat je instelt op de pagina Integraties. Zijn aanroepen worden geweigerd met 402 en spend_cap_reached zodra de client of je account zijn maandelijkse uitgavenlimiet bereikt, en met 402 en metered_billing_inactive zolang verbruiksafrekening niet actief is. Een lesplan kost 10 credits, een beurt met de tutor 1 credit en een woordenlijstgeneratie 3 credits, zodat de units die GET /v1/usage meldt met die gewichten naar credits om te rekenen zijn. Een aanroep die een app voor een andere gebruiker doet, met een token uit een autorisatiecode, verbruikt altijd het tegoed van die gebruiker, wat de modus van de client ook is.

Bewaar geheimen en tokens op een server

Het clientgeheim hoort op een server die je zelf beheert, nooit in een webpagina, een browserextensie of een app-bundel, waar iedereen het kan lezen. Een native app is een publieke client en heeft geen geheim. Noch /v1/ noch het token-endpoint beantwoordt een cross-origin preflight, dus een browser op een andere site kan ze sowieso niet aanroepen.

Clients beheren

Op de pagina Integraties, op app.getlingara.com/admin, maak je clients aan, hernoem je ze en verwijder je ze, wijzig je wat elke client mag en op welke versie hij is vastgezet, en maak je zijn geheimen aan en trek je ze in. Een client verwijderen stopt meteen elk toegangstoken dat hij heeft, en beëindigt de toestemming die elke gebruiker hem heeft gegeven. Een geheim intrekken stopt meteen elk toegangstoken waarvoor dat geheim is ingeruild. Het inperken van de scopes van een client geldt ook meteen; ze uitbreiden, of zijn versie wijzigen, geldt vanaf de volgende inruil.

Een geheim roteren

Een client kan twee geheimen tegelijk hebben. Om te roteren maak je een nieuw geheim aan, rol je het uit en trek je het oude in zodra de datum 'Laatst gebruikt' ervan op de pagina Integraties niet meer verandert. Een proces dat het nieuwe geheim al heeft maar nog een token van het oude bezit, krijgt één keer 401 en ruilt opnieuw in. Het enige geheim van een client kan niet worden ingetrokken: maak eerst de vervanger aan, of verwijder de client.

Als een vertaling afwijkt van de Engelse referentie, is de Engelse referentie juist.