Autenticazione

Versione API 2026-10-affable-towhee

Ogni chiamata all'API di Lingara porta con sé un token di accesso. Un server ne ottiene uno scambiando l'ID client e il segreto di un client OAuth presso l'endpoint dei token: il grant client credentials di OAuth 2.0, per un server che agisce per conto proprio. Crea i client nella pagina Integrazioni dell'app web di Lingara, all'indirizzo app.getlingara.com/admin.

Una sessione o un client

Le app di Lingara ti fanno accedere con una sessione, che possiede ogni scope e consuma la quota del tuo piano. Un client è più ristretto: quando lo crei scegli gli scope che gli sono consentiti, e ogni token di accesso che ottiene porta solo gli scope che richiede.

Tre valori

L'ID client inizia con lgr_cid_ e identifica il client presso l'endpoint dei token. Non è un segreto.

Il segreto del client inizia con lgr_cs_ e viene inviato solo all'endpoint dei token. Viene mostrato una sola volta, quando lo crei: copialo in quel momento, perché Lingara ne conserva solo un hash.

Il token di accesso inizia con lgr_at_ e dura un'ora. Va nell'intestazione Authorization: Bearer delle chiamate sotto /v1/, e da nessun'altra parte. È l'unico valore che va in quell'intestazione: un segreto del client inviato lì viene rifiutato con 401.

Ottieni un token di accesso

Invia con POST un modulo all'endpoint dei token con grant_type=client_credentials. Invia l'ID client e il segreto tramite autenticazione HTTP Basic oppure come campi del modulo client_id e client_secret, mai entrambi. scope è un elenco, separato da spazi, di scope consentiti al client; omettilo per ottenere tutti gli scope consentiti al client. Il comando qui sotto richiede solo usage:read, lo scope di cui ha bisogno l'esempio GET /v1/usage più avanti.

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"

La risposta contiene access_token, token_type (Bearer), expires_in (3600, in secondi) e scope, gli scope che il token possiede effettivamente. Uno scambio non riuscito risponde nel formato di errore OAuth, {error, error_description}, non nella busta {code, error} di /v1/. Un segreto errato o revocato, o un client eliminato, viene rifiutato con 401 e invalid_client. Uno scope che il client non può richiedere fa rifiutare l'intero scambio con 400 e invalid_scope; non viene mai ristretto in silenzio.

Agisci per conto di un altro utente Lingara

Un'app che agisce per conto di un altro utente Lingara usa il grant con codice di autorizzazione. Indirizza il browser dell'utente all'URL di autorizzazione con response_type=code, client_id, una redirect_uri che corrisponda esattamente a una di quelle che hai registrato, scope, state e una code_challenge S256. L'utente vede la pagina di consenso di Lingara e torna alla tua redirect_uri con code, state e iss. Verifica che state sia quello che hai inviato e che iss sia https://api.getlingara.com prima di usare il codice.

PKCE è obbligatorio

Ogni client usa PKCE, solo con il metodo S256. Genera un code_verifier casuale, invia il suo hash SHA-256, codificato in base64url, come code_challenge con code_challenge_method=S256, e conserva il verifier per lo scambio. Una richiesta senza metodo, o con plain, viene rifiutata con invalid_request.

Scambia il codice

Entro 60 secondi, invia con POST all'endpoint dei token grant_type=authorization_code, code, la stessa redirect_uri e il code_verifier, autenticandoti come client; un client pubblico invia solo client_id. La risposta aggiunge un refresh_token, che inizia con lgr_rt_. Il codice inizia con lgr_ac_ e funziona una sola volta: un secondo utilizzo viene rifiutato con invalid_grant e chiude i token emessi dal primo scambio.

Aggiorna

Quando il token di accesso scade, invia con POST all'endpoint dei token grant_type=refresh_token e il refresh_token, autenticandoti di nuovo come client. Ogni aggiornamento restituisce un nuovo token di aggiornamento: conserva solo il più recente. Esegui gli aggiornamenti uno alla volta: un vecchio token di aggiornamento usato più di 60 secondi dopo essere stato sostituito viene considerato rubato e chiude i token di quell'installazione con invalid_grant. Un token di aggiornamento non usato per 30 giorni scade. L'endpoint dei token limita le richieste per indirizzo, quindi aggiorna solo quando un token si esaurisce.

Le app native sono client pubblici

Un'app desktop, mobile o da riga di comando non può custodire un segreto, quindi è un client pubblico: non ha un segreto, invia solo client_id all'endpoint dei token e registra un reindirizzamento di loopback come http://127.0.0.1/callback (qualsiasi porta) o uno schema ad uso privato come com.example.app:/callback. L'utente vede la pagina di consenso ogni volta. Una pagina web non può essere un client: né l'endpoint dei token né /v1/ rispondono a una richiesta preflight cross-origin.

Quando l'utente rimuove la tua app

L'utente può rimuovere la tua app in qualsiasi momento in App collegate, oppure disinstallandola se l'ha installata, e la sua chiamata successiva fallisce con 401. Quando l'utente esce dalla tua app, revoca il suo token di aggiornamento all'endpoint di revoca, che chiude i token di quell'installazione.

Quando il token scade

Dopo un'ora, /v1/ risponde 401 con il codice unauthorized e un errore che inizia con invalid_token. Scambia di nuovo quando una chiamata riceve 401, o poco prima che expires_in si esaurisca, e riprova la chiamata una volta. Se è lo scambio stesso a fallire con invalid_client o invalid_scope, il client o il suo segreto è stato eliminato, revocato o ristretto: fermati e correggilo nella pagina Integrazioni, perché riprovare non può riuscire. Conserva il token tra una chiamata e l'altra: l'endpoint dei token limita gli scambi per client e per indirizzo, e un programma che scambia a ogni chiamata viene rifiutato con 429 e rate_limited entro l'ora (attendi Retry-After). Questo grant non ha un token di aggiornamento: si scambia di nuovo il segreto.

I token di accesso raggiungono solo le route dell'API

Un token di accesso funziona solo sulle route sotto /v1/. Inviato a qualsiasi altra route di Lingara viene rifiutato con 401, e il corpo inizia con api_token_not_accepted, come testo semplice o all'interno di un campo error, mai nella busta {code, error} usata dalle route /v1/. Invia il token di accesso nell'intestazione Authorization, come mostrato sotto.

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

Scope

Ogni operazione richiede esattamente uno scope, indicato nella sua pagina. Un token di accesso senza quello scope viene rifiutato con 403 e il codice insufficient_scope. Per chiamare l'operazione, richiedi il suo scope durante lo scambio, se è consentito al client. La tabella qui sotto elenca ogni scope e le operazioni che consente.

Chi paga una chiamata

Un client viene fatturato in uno di due modi, scelto quando viene creato. Un client allowance consuma la quota del suo proprietario, la stessa quota delle tue app, e anche i suoi token di accesso la consumano; GET /v1/usage mostra quanto ne rimane. Un client metered non consuma quota: viene fatturato a credito tramite un abbonamento con fatturazione a consumo che configuri nella pagina Integrazioni. Le sue chiamate vengono rifiutate con 402 e spend_cap_reached non appena il client o il tuo account raggiunge il limite di spesa mensile, e con 402 e metered_billing_inactive finché la fatturazione a consumo non è attiva. Un piano di lezione vale 10 crediti, un turno con il tutor 1 credito e una generazione di vocaboli 3 crediti, quindi le units riportate da GET /v1/usage si convertono in crediti con questi pesi. Una chiamata che un'app effettua per conto di un altro utente, con un token ottenuto da un codice di autorizzazione, consuma sempre la quota di quell'utente, qualunque sia la modalità del client.

Tieni segreti e token su un server

Il segreto del client va tenuto su un server che controlli, mai in una pagina web, in un'estensione del browser o nel pacchetto di un'app, dove chiunque può leggerlo. Un'app nativa è un client pubblico e non possiede alcun segreto. Né /v1/ né l'endpoint dei token rispondono a una richiesta preflight cross-origin, quindi un browser su un altro sito non può comunque chiamarli.

Gestisci i client

Nella pagina Integrazioni, all'indirizzo app.getlingara.com/admin, crea, rinomina ed elimina i client, cambia cosa può fare ciascuno e a quale versione è fissato, e crea e revoca i suoi segreti. Eliminare un client blocca subito ogni token di accesso che possiede e chiude l'autorizzazione che ogni utente gli ha concesso. Revocare un segreto blocca subito ogni token di accesso ottenuto in cambio di quel segreto. Anche restringere gli scope di un client si applica subito; ampliarli, o cambiarne la versione, si applica dallo scambio successivo.

Ruota un segreto

Un client può avere due segreti contemporaneamente. Per ruotare, crea un nuovo segreto, distribuiscilo e revoca quello vecchio quando la sua data di «Ultimo utilizzo» nella pagina Integrazioni smette di cambiare. Un processo che ha già il nuovo segreto ma possiede ancora un token ottenuto con il vecchio riceve un solo 401 e scambia di nuovo. L'unico segreto di un client non può essere revocato: crea prima il suo sostituto, oppure elimina il client.

In caso di discrepanza tra una traduzione e il riferimento in inglese, fa fede il riferimento in inglese.