Référence complète de l'API : developer.universally.com contient la spécification en direct pour l'API Traducteur et l'API Plateforme, avec tous les champs, codes d'état et exemples de réponses. Cette page couvre ce qu'il faut savoir à ce sujet.
Chaque requête de l'API Universally est authentifiée avec une clé API passée dans l'en-tête HTTP X-API-Key.
X-API-Key: your_api_key_here
Deux types de clé
Ils ne sont pas interchangeables, et l'envoi du mauvais retourne API_KEY_INVALID. Celui dont vous avez besoin dépend du service que vous appelez.
| Clé de projet | Clé de l'API Plateforme | |
|---|---|---|
| Ressemble à | une chaîne de 64 caractères | commence par pak_ |
| Appartient à | un projet | un espace de travail |
| Créé dans | les Paramètres API du projet | l'onglet Clés API de l'espace de travail |
| Fonctionne sur | translator.universally.com, et les points de connexion sur api.universally.com |
l'API Plateforme sur api.universally.com |
| Expire | no | oui, vous choisissez quand |
| Portée | tout ce que la clé du projet peut faire | uniquement les permissions cochées lors de sa création |
La traduction de contenu utilise la clé de projet. La gestion des projets, des langues et des chaînes stockées à partir de vos propres outils utilise une clé d'API Plateforme.
Obtenir une clé de projet
Une clé de projet est générée automatiquement lorsque vous créez un projet. Ouvrez le projet et accédez à Paramètres API pour la visualiser, la copier ou la régénérer. Sa visualisation nécessite l'autorisation des clés API. Il n'existe pas de point de terminaison pour en créer une.
La régénération de la clé invalide immédiatement la précédente. Toute intégration utilisant l'ancienne clé recevra des erreurs API_KEY_INVALID jusqu'à ce que vous la mettiez à jour.
Obtenir une clé d'API Plateforme
Ouvrez l'espace de travail et accédez à Clés API, puis créez-en une. Consultez Trouver votre clé API pour connaître les champs, y compris l'expiration et la liste des permissions, et notez que la clé est affichée une seule fois et ne peut pas être récupérée par la suite.
Garder votre clé en sécurité
Votre clé peut dépenser les mots traduits de votre forfait, alors traitez-la comme un mot de passe :
- Envoyez des requêtes depuis un serveur, une fonction edge ou un job backend. N'intégrez jamais la clé dans du JavaScript de navigateur, des bundles d'applications mobiles ou tout client qu'un utilisateur peut inspecter.
- Gardez la clé hors du contrôle de version. Chargez-la à partir d'une variable d'environnement ou d'un gestionnaire de secrets.
- Si un client (un navigateur ou une application) a besoin de contenu traduit, acheminez la requête via votre propre backend afin que la clé reste côté serveur.
Comme le Traducteur autorise les requêtes cross-origin, une clé compromise pourrait être utilisée depuis n'importe où. Si vous suspectez que votre clé est exposée, régénérez-la dans le tableau de bord.
Vérifier une clé
Pour vérifier qu'une clé est valide et voir à quel site elle appartient, appelez le point d'accès de vérification sur le service API :
curl https://api.universally.com/connect/keys/verify \
-H "X-API-Key: your_api_key_here"
{
"success": true,
"data": {
"valid": true,
"siteId": "site_123",
"domain": "example.com"
},
"message": "API key is valid.",
"code": "KEY_VALID"
}
Ceci est utile lors de la configuration pour confirmer qu'une intégration est connectée au bon site avant d'envoyer du contenu réel.
Erreurs d'authentification
| Code | HTTP | Signification |
|---|---|---|
CLÉ_API_MANQUANTE |
401 | Aucun en-tête X-API-Key n'a été envoyé. |
CLÉ_API_FORMAT_INVALIDE |
401 | La clé n'est pas d'un format reconnu. |
CLÉ_API_MALFORMÉE |
401 | La clé n'a pas pu être analysée. |
CLÉ_API_INVALIDE |
401 | La clé est bien formée mais n'est pas reconnue, souvent après une régénération. |
Voir Erreurs et Limites pour le tableau complet.