Authentification

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

Chaque appel à l'API Lingara porte un jeton d'accès. Un serveur en obtient un en échangeant l'identifiant du client et le secret d'un client OAuth auprès du point de terminaison de jeton : c'est l'octroi client credentials d'OAuth 2.0, pour un serveur qui agit en son propre nom. Créez des clients sur la page Intégrations de l'application web Lingara, à l'adresse app.getlingara.com/admin.

Une session ou un client

Les applications Lingara vous connectent avec une session, qui détient toutes les portées et consomme le quota de votre abonnement. Un client est plus restreint : vous choisissez les portées qui lui sont autorisées lorsque vous le créez, et chaque jeton d'accès qu'il obtient ne porte que les portées qu'il demande.

Trois valeurs

L'identifiant du client commence par lgr_cid_ et désigne le client auprès du point de terminaison de jeton. Ce n'est pas un secret.

Le secret du client commence par lgr_cs_ et n'est envoyé qu'au point de terminaison de jeton. Il n'est affiché qu'une fois, lors de sa création : copiez-le à ce moment-là, car Lingara n'en conserve qu'une empreinte.

Le jeton d'accès commence par lgr_at_ et dure une heure. Il se place dans l'en-tête Authorization: Bearer des appels sous /v1/, et nulle part ailleurs. C'est la seule valeur qui a sa place dans cet en-tête : un secret de client envoyé là est refusé avec 401.

Obtenir un jeton d'accès

Envoyez un formulaire en POST au point de terminaison de jeton avec grant_type=client_credentials. Transmettez l'identifiant du client et le secret soit par authentification HTTP Basic, soit dans les champs de formulaire client_id et client_secret, jamais les deux. scope est une liste, séparée par des espaces, de portées autorisées au client ; omettez-la pour obtenir toutes les portées autorisées au client. La commande ci-dessous ne demande que usage:read, la portée dont a besoin l'exemple GET /v1/usage plus bas.

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 réponse contient access_token, token_type (Bearer), expires_in (3600, en secondes) et scope, les portées que le jeton détient réellement. Un échange échoué répond au format d'erreur OAuth, {error, error_description}, et non dans l'enveloppe {code, error} de /v1/. Un secret erroné ou révoqué, ou un client supprimé, est refusé avec 401 et invalid_client. Une portée que le client ne peut pas demander fait refuser l'échange entier avec 400 et invalid_scope ; elle n'est jamais restreinte en silence.

Agir pour un autre utilisateur Lingara

Une application qui agit pour un autre utilisateur Lingara utilise l'octroi par code d'autorisation. Envoyez le navigateur de l'utilisateur vers l'URL d'autorisation avec response_type=code, client_id, une redirect_uri identique à l'une de celles que vous avez enregistrées, scope, state et un code_challenge S256. L'utilisateur voit la page de consentement de Lingara et revient sur votre redirect_uri avec code, state et iss. Vérifiez que state est celui que vous avez envoyé et que iss vaut https://api.getlingara.com avant d'utiliser le code.

PKCE est obligatoire

Chaque client utilise PKCE, avec la seule méthode S256. Générez un code_verifier aléatoire, envoyez son empreinte SHA-256, encodée en base64url, comme code_challenge avec code_challenge_method=S256, et conservez le vérificateur pour l'échange. Une requête sans méthode, ou avec plain, est refusée avec invalid_request.

Échanger le code

Dans un délai de 60 secondes, envoyez en POST au point de terminaison de jeton grant_type=authorization_code, code, la même redirect_uri et le code_verifier, en vous authentifiant en tant que client ; un client public n'envoie que client_id. La réponse contient en plus un refresh_token, qui commence par lgr_rt_. Le code commence par lgr_ac_ et ne fonctionne qu'une fois : une seconde utilisation est refusée avec invalid_grant et met fin aux jetons émis lors du premier échange.

Actualiser

Quand le jeton d'accès expire, envoyez en POST au point de terminaison de jeton grant_type=refresh_token et le refresh_token, en vous authentifiant de nouveau en tant que client. Chaque actualisation renvoie un nouveau jeton d'actualisation : ne conservez que le plus récent. Effectuez vos actualisations l'une après l'autre : un ancien jeton d'actualisation utilisé plus de 60 secondes après son remplacement est considéré comme volé et met fin aux jetons de cette installation avec invalid_grant. Un jeton d'actualisation inutilisé pendant 30 jours expire. Le point de terminaison de jeton limite les requêtes par adresse : n'actualisez donc que lorsqu'un jeton arrive à échéance.

Les applications natives sont des clients publics

Une application de bureau, mobile ou en ligne de commande ne peut pas garder un secret : c'est donc un client public. Elle n'a pas de secret, n'envoie que client_id au point de terminaison de jeton et enregistre une redirection de bouclage comme http://127.0.0.1/callback (n'importe quel port) ou un schéma privé comme com.example.app:/callback. L'utilisateur voit la page de consentement à chaque fois. Une page web ne peut pas être un client : ni le point de terminaison de jeton ni /v1/ ne répondent à une requête préliminaire cross-origin.

Quand l'utilisateur retire votre application

L'utilisateur peut retirer votre application à tout moment dans Applications connectées, ou en la désinstallant s'il l'a installée, et son appel suivant échoue avec 401. Quand l'utilisateur se déconnecte de votre application, révoquez son jeton d'actualisation au point de terminaison de révocation, ce qui met fin aux jetons de cette installation.

Quand le jeton expire

Au bout d'une heure, /v1/ répond 401 avec le code unauthorized et une erreur commençant par invalid_token. Échangez de nouveau lorsqu'un appel reçoit 401, ou peu avant l'échéance de expires_in, et relancez l'appel une fois. Si l'échange lui-même échoue avec invalid_client ou invalid_scope, le client ou son secret a été supprimé, révoqué ou restreint : arrêtez-vous et corrigez-le sur la page Intégrations, car une nouvelle tentative ne peut pas aboutir. Conservez le jeton entre les appels : le point de terminaison de jeton limite les échanges par client et par adresse, et un programme qui échange à chaque appel est refusé avec 429 et rate_limited dans l'heure (attendez Retry-After). Cet octroi n'a pas de jeton d'actualisation : c'est le secret qui est échangé de nouveau.

Les jetons d'accès n'atteignent que les routes de l'API

Un jeton d'accès ne fonctionne que sur les routes sous /v1/. Envoyé à toute autre route Lingara, il est refusé avec 401, et le corps commence par api_token_not_accepted, en texte brut ou dans un champ error, jamais dans l'enveloppe {code, error} qu'utilisent les routes /v1/. Envoyez le jeton d'accès dans l'en-tête Authorization, comme ci-dessous.

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

Portées

Chaque opération nécessite exactement une portée, indiquée sur sa page. Un jeton d'accès sans cette portée est refusé avec 403 et le code insufficient_scope. Pour appeler l'opération, demandez sa portée lors de l'échange, si elle est autorisée au client. Le tableau ci-dessous liste chaque portée et les opérations qu'elle autorise.

Qui paie un appel

Un client est facturé de l'une de deux façons, choisie à sa création. Un client allowance consomme le quota de son propriétaire, le même quota que vos applications, et ses jetons d'accès le consomment aussi ; GET /v1/usage indique ce qu'il en reste. Un client metered ne consomme aucun quota : il est facturé au crédit via un abonnement de facturation à l'usage que vous configurez sur la page Intégrations. Ses appels sont refusés avec 402 et spend_cap_reached dès que le client ou votre compte atteint sa limite de dépenses mensuelle, et avec 402 et metered_billing_inactive tant que la facturation à l'usage n'est pas active. Un plan de leçon vaut 10 crédits, un tour de tuteur 1 crédit et une génération de vocabulaire 3 crédits : les units que renvoie GET /v1/usage se convertissent donc en crédits selon ces poids. Un appel qu'une application effectue pour un autre utilisateur, avec un jeton issu d'un code d'autorisation, consomme toujours le quota de cet utilisateur, quel que soit le mode du client.

Gardez secrets et jetons sur un serveur

Le secret du client a sa place sur un serveur que vous contrôlez, jamais dans une page web, une extension de navigateur ou un paquet d'application, où n'importe qui peut le lire. Une application native est un client public et ne détient aucun secret. Ni /v1/ ni le point de terminaison de jeton ne répondent à une requête préliminaire cross-origin, si bien qu'un navigateur sur un autre site ne peut de toute façon pas les appeler.

Gérer les clients

Sur la page Intégrations, à l'adresse app.getlingara.com/admin, créez, renommez et supprimez des clients, modifiez ce que chacun peut faire et la version à laquelle il est épinglé, et créez et révoquez ses secrets. Supprimer un client arrête immédiatement tous les jetons d'accès qu'il détient et met fin à l'autorisation que chaque utilisateur lui a accordée. Révoquer un secret arrête immédiatement tous les jetons d'accès obtenus en échange de ce secret. Restreindre les portées d'un client s'applique aussi immédiatement ; les élargir, ou changer sa version, s'applique à partir de l'échange suivant.

Renouveler un secret

Un client peut détenir deux secrets à la fois. Pour renouveler, créez un nouveau secret, déployez-le, puis révoquez l'ancien une fois que sa date « Dernière utilisation » sur la page Intégrations cesse de changer. Un processus qui a déjà le nouveau secret mais détient encore un jeton issu de l'ancien reçoit un seul 401 et échange de nouveau. Le seul secret d'un client ne peut pas être révoqué : créez d'abord son remplaçant, ou supprimez le client.

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