Prise en main

Authentification

Créer des clés API, les envoyer avec les requêtes et choisir les portées.

Afficher en Markdown

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 :

  1. Choisissez Nouveau, donnez un nom à la clé (et éventuellement une description).
  2. Sélectionnez les portées dont la clé a besoin.
  3. 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 :

text
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 :

bash
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.tts Synthèse vocale AYETO Synthèse vocale
ayeto.data_loader Texte du fichier AYETO Convertir un fichier en texte

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.

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.