Comment créer un client OAuth

Version de l'API 2026-10-affable-towhee

Avant d'appuyer sur « Créer un client » sur la page Intégrations, décidez de trois choses : ce que le client peut faire, quel processus détient son secret, et qui paie ses appels. Le guide Authentification énonce les règles ; cette page les applique à deux entreprises fictives, Luba et Farducks.

Luba : le Dive Deck

Luba exploite des sous-marins autonomes comme service de transport et de covoiturage. Son Dive Deck montre à chaque passager, sur l'écran de la cabine, une phrase de la plongée dans la langue qu'il apprend, et l'équipe des opérations de Luba surveille ce qu'il reste du quota.

Luba crée un seul client, Luba Dive Deck, autorisé à « Générer du vocabulaire » (vocab:generate) et à « Lire l'utilisation » (usage:read), facturé sur « Le quota de votre forfait » (allowance). Deux processus le partagent, et chacun ne demande lors de l'échange que la portée dont il a besoin. Un échange qui omet scope obtient toutes les portées autorisées au client ; un échange qui demande une portée non autorisée au client est refusé en entier avec invalid_scope, jamais restreint en silence.

Le serveur de répartition écrit les phrases de chaque plongée. Il ne demande que vocab:generate, si bien qu'un jeton qui fuiterait de ce serveur ne peut pas lire l'utilisation de 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}'

Le tableau de bord des opérations est un second processus côté serveur, avec le même identifiant du client et le même secret. Il ne demande que usage:read, et lit ce qu'il reste du quota.

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"

Les deux processus tournent sur les serveurs de Luba. La tablette de la cabine demande les phrases au serveur de répartition et ne détient jamais le secret ni un jeton, car tout ce qui se trouve sur un appareil qu'un passager peut toucher peut être lu. La section « Gardez secrets et jetons sur un serveur » du guide Authentification explique pourquoi.

Le même client, sous forme de projet à cloner et exécuter : integrations/luba-dive-deck

Farducks : Batter Rewards

Farducks est une chaîne de supérettes de fish and chips. Pendant qu'une commande frit, l'application de fidélité Batter Rewards demande au backend de Farducks un court plan de cours, puis le relit. L'application et les caisses appellent le backend de Farducks, jamais Lingara, si bien qu'aucune des deux ne détient le secret.

Farducks crée un seul client, Farducks Batter Rewards, autorisé à « Créer des plans de cours » (lesson_plans:write) et à « Lire les plans de cours » (lesson_plans:read), facturé sur « Le quota de votre forfait » (allowance). C'est aujourd'hui le seul mode de facturation avec lequel un client peut être créé, et la facturation d'un client est fixée à sa création. L'autre mode, metered (« Paiement à l'usage »), est décrit dans la section « Qui paie un appel » du guide Authentification.

Le backend ne demande que lesson_plans:write et crée le plan. La réponse est diffusée en flux, et son événement started porte le plan_id du plan.

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}'

Donnez à ID la valeur de ce plan_id, puis demandez lesson_plans:read et relisez le plan. Un même échange peut demander plusieurs portées du client, séparées par des espaces dans scope ; chaque commande ici n'en demande qu'une, car chacune est composée à partir d'un seul appel.

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 jour, le secret est collé dans un ticket de support. Sur la page Intégrations, Farducks appuie sur « Nouveau secret » et le déploie sur le backend, attend que la date « Dernière utilisation » de l'ancien secret cesse de changer, puis appuie sur « Révoquer » pour l'ancien secret. Chaque jeton d'accès obtenu en échange de l'ancien secret est refusé dès cet instant. La section « Renouveler un secret » du guide Authentification donne la limite de deux secrets et explique pourquoi le seul secret d'un client ne peut pas être révoqué.

Le même client, sous forme de projet à cloner et exécuter : integrations/farducks-batter-rewards

Pour aller plus loin

Le guide Authentification couvre les erreurs de l'échange, la marche à suivre quand un jeton expire, et la règle de renouvellement. Le guide Versions couvre la version à laquelle un client est fixé, et comment en choisir une autre pour un seul appel.

En cas de divergence entre une traduction et la référence en anglais, la référence en anglais fait foi.