# Authentification

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

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](#portees) 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](chat.md) |
| `ayeto.conversation` | Conversations AYETO | [Conversations](conversations.md) |
| `ayeto.assistant` | Assistants AYETO | Lister les [assistants](assistants.md) et leurs avatars |
| `ayeto.workflow` | Workflows AYETO (lecture et exécution) | Lire et exécuter des [workflows](workflows.md), exécutions, approbations |
| `ayeto.workflow.write` | Workflows AYETO (modification) | Créer, modifier, publier, importer et supprimer des [workflows](workflows.md) |
| `ayeto.booster.database` | Base de données booster AYETO (lecture) | Lire les enregistrements de la [base de données booster](booster-database.md) |
| `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](files-and-media.md#synthese-vocale) |
| `ayeto.data_loader` | Texte du fichier AYETO | [Convertir un fichier en texte](files-and-media.md#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.