Come creare un client OAuth

Versione API 2026-10-affable-towhee

Prima di premere «Crea client» nella pagina Integrazioni, decidi tre cose: cosa può fare il client, quale processo custodisce il suo segreto e chi paga le sue chiamate. La guida Autenticazione stabilisce le regole; questa pagina le applica a due aziende fittizie, Luba e Farducks.

Luba: il Dive Deck

Luba gestisce sottomarini autonomi come servizio di trasporto e ride-sharing. Il suo Dive Deck mostra a ogni passeggero una frase dell'immersione sullo schermo della cabina, nella lingua che sta imparando, e il team operativo di Luba tiene d'occhio quanta quota resta.

Luba crea un solo client, Luba Dive Deck, a cui sono consentiti «Genera vocabolario» (vocab:generate) e «Leggi l'utilizzo» (usage:read), fatturato su «L'utilizzo incluso nel tuo piano» (allowance). Due processi lo condividono, e ciascuno chiede nello scambio solo lo scope di cui ha bisogno. Uno scambio che omette scope ottiene ogni scope consentito al client; uno che chiede uno scope non consentito al client viene rifiutato per intero con invalid_scope, mai ristretto in silenzio.

Il server di dispatch scrive le frasi di ogni immersione. Chiede solo vocab:generate, quindi un token che trapela da lì non può leggere l'utilizzo di Luba.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

La dashboard operativa è un secondo processo lato server con lo stesso ID client e lo stesso segreto. Chiede solo usage:read, e legge quanta quota resta.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -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" | jq -r '.access_token // error(.error)')"

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

Entrambi i processi girano sui server di Luba. Il tablet in cabina chiede le frasi al server di dispatch e non custodisce mai il segreto né un token, perché tutto ciò che sta su un dispositivo che un passeggero può toccare può essere letto. La sezione «Tieni segreti e token su un server» della guida Autenticazione spiega perché.

Lo stesso client come progetto da clonare ed eseguire: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks è una catena di negozi di fish and chips. Mentre un ordine frigge, l'app fedeltà Batter Rewards chiede al backend di Farducks un breve piano di lezione, poi lo rilegge. L'app e le casse chiamano il backend di Farducks, mai Lingara, quindi nessuna delle due custodisce il segreto.

Farducks crea un solo client, Farducks Batter Rewards, a cui sono consentiti «Crea piani di lezione» (lesson_plans:write) e «Leggi i piani di lezione» (lesson_plans:read), fatturato su «L'utilizzo incluso nel tuo piano» (allowance). È l'unica fatturazione con cui oggi si può creare un client, e la fatturazione di un client è fissata al momento della creazione. L'altra modalità, metered («Pagamento a consumo»), è descritta nella sezione «Chi paga una chiamata» della guida Autenticazione.

Il backend chiede solo lesson_plans:write e crea il piano. La risposta arriva in streaming, e il suo evento started contiene il plan_id del piano.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

Imposta ID su quel plan_id, poi chiedi lesson_plans:read e rileggi il piano. Uno scambio può chiedere più scope del client, separati da spazi in scope; ogni comando qui ne chiede uno, perché ciascuno è composto da una singola chiamata.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

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

Un giorno il segreto viene incollato in un ticket di assistenza. Nella pagina Integrazioni, Farducks preme «Nuovo segreto» e lo distribuisce al backend, aspetta che la data di «Ultimo utilizzo» del vecchio segreto smetta di cambiare, poi preme «Revoca» sul vecchio segreto. Da quel momento ogni token di accesso ottenuto in cambio del vecchio segreto viene rifiutato. La sezione «Ruota un segreto» della guida Autenticazione riporta il limite di due segreti e spiega perché l'unico segreto di un client non può essere revocato.

Lo stesso client come progetto da clonare ed eseguire: integrations/farducks-batter-rewards

Dove andare ora

La guida Autenticazione tratta gli errori dello scambio, cosa fare quando un token scade e la regola di rotazione. La guida Versioni tratta la versione a cui è fissato un client e come sceglierne un'altra per una singola chiamata.

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