Chaque requête adressée à l'API est authentifiée par une clé API. Une clé appartient à l'utilisateur qui l'a créée : les requêtes faites avec elle agissent au nom de cet utilisateur, voient ce que cet utilisateur peut voir et dépensent ses crédits (ou ceux de son organisation).
Clés API
Créez les clés dans l'application AYETO sous Profil → Clés API :
- Choisissez Nouveau, donnez un nom à la clé (et éventuellement une description).
- Sélectionnez les portées dont la clé a besoin.
- Copiez la clé depuis la boîte de dialogue de confirmation. La clé complète n'est affichée qu'une seule fois ; ensuite, l'application n'en montre que le début et la fin pour que vous puissiez la reconnaître.
Une clé ressemble à ceci :
ayeto-1f0c2b7e9a4d4c6f8e3b5a7d9c1e2f40a8b6c4d2e0f1a3b5c7d9e1f2a4b6c8d0
Les clés n'expirent pas. Pour révoquer une clé, supprimez-la au même endroit ; les requêtes avec une clé supprimée échouent immédiatement.
Traitez une clé comme un mot de passe : conservez-la sur votre serveur ou dans un coffre de secrets, jamais dans un dépôt de code source ni dans du code qui s'exécute dans le navigateur de quelqu'un d'autre.
Envoyer la clé
Envoyez la clé dans l'en-tête uni-api-key de chaque requête :
curl -X POST "https://ayeto.ai/api/v3/conversation/find" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit_from": 0, "limit_to": 5}'
Aucune autre authentification (cookies, jetons bearer) n'est nécessaire ni acceptée par les endpoints de cette documentation.
Portées
Une portée autorise une clé à appeler un groupe d'endpoints. Ne donnez à chaque clé que les
portées dont elle a besoin. Une clé avec toutes les portées (*) peut appeler tous les
endpoints.
| Portée | Affichée dans l'application comme | Autorise |
|---|---|---|
* |
toutes les portées | Tous les endpoints, y compris ceux qui exigent une portée non listée ci-dessous. |
ayeto.chat |
Chat AYETO | Chat |
ayeto.conversation |
Conversations AYETO | Conversations |
ayeto.assistant |
Assistants AYETO | Lister les assistants et leurs avatars |
ayeto.workflow |
Workflows AYETO (lecture et exécution) | Lire et exécuter des workflows, exécutions, approbations |
ayeto.workflow.write |
Workflows AYETO (modification) | Créer, modifier, publier, importer et supprimer des workflows |
ayeto.booster.database |
Base de données booster AYETO (lecture) | Lire les enregistrements de la base de données booster |
ayeto.booster.database.write |
Base de données booster AYETO (écriture) | Créer, mettre à jour et supprimer des enregistrements, verrous |
ayeto.booster.storage |
Stockage de fichiers booster AYETO (lecture) | Lister les fichiers d'un panneau booster, liens de téléchargement |
ayeto.booster.storage.write |
Stockage de fichiers booster AYETO (écriture) | Téléverser, déplacer et supprimer les fichiers d'un panneau |
ayeto.tts |
Synthèse vocale AYETO | Synthèse vocale |
ayeto.data_loader |
Texte du fichier AYETO | Convertir un fichier en texte |
ayeto.embeddings |
Embeddings AYETO | Embeddings |
Un endpoint qui exige plusieurs portées a besoin de toutes ces portées sur la clé. Les endpoints qui indiquent « n'importe quelle clé API » comme portée acceptent toute clé valide. Le tableau récapitulatif de chaque endpoint indique la portée qu'il exige.
L'application propose aussi la portée Connecteurs AYETO (ayeto.connector). Elle est
utilisée par les clients de bureau AYETO lorsqu'ils s'associent à votre compte et n'est pas
nécessaire pour cette API. Une clé créée par l'association d'un client de bureau n'a que
cette portée et ne peut pas appeler les endpoints ci-dessus.
Panneaux booster agissant pour une personne connectée
Un panneau booster avec des comptes utilisateurs peut permettre de se connecter avec un compte AYETO. Si le propriétaire du panneau l'autorise, le panneau peut alors appeler cette API en tant que cette personne : l'écran de connexion liste ce que le panneau demande (des portées du tableau ci-dessus, ou toutes) et la personne l'accepte en se connectant.
- Le panneau envoie le jeton de session reçu à la connexion (il commence par
bpu_) dans l'en-têteuni-api-key, exactement comme une clé API. Aucun autre en-tête n'est nécessaire. - La requête s'exécute en tant que compte de la personne avec les portées acceptées, jamais plus que ce que le panneau demande à ce moment. Chaque endpoint utilise les organisations, assistants et workflows accessibles au compte, comme avec la propre clé API du compte, et consomme ses crédits.
- Les endpoints qui acceptent n'importe quelle clé API acceptent aussi un tel jeton.
- La déconnexion du panneau, la fin de la session, la perte du droit de se connecter au panneau (par
ex. en quittant son organisation) ou un réglage plus restreint du panneau mettent fin à l'accès en
une minute ; le jeton est alors refusé comme une clé invalide (
401). - Les sessions des comptes du panneau connectés par mot de passe ou par code e-mail n'obtiennent jamais d'accès à l'API.
Erreurs d'authentification
| Statut | detail |
Cause |
|---|---|---|
422 |
erreur de validation de la requête mentionnant uni-api-key |
L'en-tête uni-api-key est absent. |
401 |
API key not provided |
L'en-tête uni-api-key est vide. |
401 |
API key is invalid |
La clé n'existe pas, a été supprimée ou désactivée, ou il lui manque une portée exigée par l'endpoint. |
Une portée manquante est signalée de la même manière qu'une clé inconnue, afin qu'une réponse
ne révèle jamais si une clé existe. Une authentification échouée reçoit sa réponse après un
court délai volontaire ; ne relancez pas un 401 en boucle, corrigez plutôt la clé ou ses
portées.