API — principes¶
L'API publique est en cours de construction. Voici ce qui est déjà arrêté, pour que vous puissiez juger avant de vous engager.
Ce que le serveur reçoit, et ce qu'il ne reçoit pas¶
| Il reçoit | Il ne reçoit jamais |
|---|---|
| Une preuve d'authentification dérivée de votre mot de passe | Le mot de passe lui-même |
| Votre clé de compte enveloppée, qu'il ne peut pas ouvrir | La clé de compte en clair |
| Des enveloppes chiffrées de bout en bout | Le contenu de vos documents |
Trois choix que vous pouvez vérifier¶
L'endpoint des paramètres répond pour toute adresse, inscrite ou non. Il est nécessairement public — un client en a besoin avant de pouvoir s'authentifier. S'il ne répondait que pour les comptes existants, il serait un annuaire de nos utilisateurs, interrogeable par n'importe qui.
La connexion renvoie la même erreur qu'une adresse soit inconnue ou la clé fausse, et fait le même travail coûteux dans les deux cas. Sans cela, le temps de réponse dirait lesquelles de nos adresses existent.
Les journaux ne contiennent pas de chaîne de requête. Le format courant des serveurs web enregistre l'URL complète — c'est ainsi que des jetons d'authentification finissent en clair dans des fichiers de log. Nous journalisons le chemin, pas les paramètres.
Authentification¶
Par clé d'API à portées, affichée une seule fois à sa création, avec des limites de débit par clé. Les SDK Python et JavaScript intègrent l'enveloppe chiffrée : vous n'avez pas à l'implémenter.
Un client qui refuse le SDK peut utiliser TLS seul — ce mode est documenté comme dégradé, car le contenu est alors déchiffré à l'entrée de notre infrastructure plutôt qu'au dernier moment.
Facturation¶
À l'usage, en mots traités, comptés dans le processus de traitement et renvoyés sous forme de nombre. Aucun autre attribut du contenu n'est extrait : ni langue, ni sujet, ni entité.
Dépassement : alerte à 80 %, proposition de recharge à 100 %. Jamais de facturation surprise.