# Authentification Chaque requête API doit comporter votre clé API afin que Your AI Connector sache qui vous êtes et sur quel compte agir. Vous pouvez envoyer la clé de quatre manières différentes — toutes fonctionnent sur chaque point de terminaison acceptant l'authentification par clé API, choisissez donc celle qui convient le mieux à votre configuration. L'accès à l'API est une fonctionnalité payante. Si votre forfait ne l'inclut pas, les requêtes sont rejetées avec une erreur `403` même si la clé elle-même est valide — voir [La barrière des fonctionnalités payantes](#the-paid-feature-gate) ci-dessous. Pour générer une clé, consultez [Accès API](../integrations/api-access.md). > **HTTPS uniquement.** Toutes les requêtes doivent utiliser une connexion sécurisée. Les requêtes HTTP en clair sont rejetées avant même que l'authentification ne soit exécutée. --- ## Aperçu des quatre méthodes | Méthode | Support | Quand l'utiliser | |---|---|---| | Paramètre de requête | `?apiKey=YOUR_API_KEY` | Tests rapides et URL de navigateur | | En-tête | `X-API-Key: YOUR_API_KEY` | Intégrations en production | | En-tête Bearer | `Authorization: Bearer YOUR_API_KEY` | Intégrations en production | | Jeton d'ID Firebase | `Authorization: Bearer ` | Sessions d'applications propriétaires uniquement | Lorsque plusieurs méthodes sont présentes, le paramètre de requête est prioritaire, suivi de l'en-tête `X-API-Key`, puis du jeton Bearer. En pratique, vous n'en envoyez qu'une seule. --- ## 1. Paramètre de requête — `?apiKey=` Ajoutez votre clé à la fin de l'adresse web. C'est la forme la plus simple et elle fonctionne toujours, ce qui la rend idéale pour les tests rapides, les scripts et tout outil ancien. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", params={"apiKey": "YOUR_API_KEY"}, ) data = res.json() ``` > **Attention :** Les adresses web finissent dans l'historique du navigateur, les journaux d'accès au serveur et les journaux des proxys. Pour tout ce qui dépasse le cadre d'un test rapide, préférez l'une des méthodes d'en-tête ci-dessous afin que votre clé ne soit pas écrite sur le disque en clair. --- ## 2. En-tête `X-API-Key` Envoyez la clé dans un en-tête dédié. Cela permet de l'exclure de l'URL et constitue le choix recommandé pour la production. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts", { headers: { "X-API-Key": "YOUR_API_KEY", }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` --- ## 3. En-tête `Authorization: Bearer` Vous pouvez également transmettre la clé en tant que jeton bearer standard. C'est pratique lorsque votre client ou framework HTTP prend déjà en charge les en-têtes `Authorization`. **cURL** ```bash curl "https://api.youraiconnector.com/v1/contacts" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/contacts", { headers: { Authorization: "Bearer YOUR_API_KEY", }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/contacts", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) data = res.json() ``` L'API distingue automatiquement votre clé d'API d'un jeton de connexion, cette méthode fonctionne donc exactement comme `X-API-Key`. --- ## 4. Jeton d'ID Firebase (première partie uniquement) Si vous développez une application propriétaire qui connecte les utilisateurs via la propre connexion de Your AI Connector, vous pouvez transmettre le jeton d'ID Firebase de cet utilisateur connecté en tant que jeton bearer au lieu d'une clé d'API : ``` Authorization: Bearer ``` Le jeton est vérifié à chaque requête et est associé au compte connecté. **Cette méthode est réservée aux sessions d'applications propriétaires** — vous ne pouvez pas générer ces jetons à partir d'une intégration externe, et il n'existe aucun moyen d'en obtenir un sans passer par la connexion normale à l'application. Pour les intégrations serveur à serveur et tierces, utilisez une clé d'API (méthodes 1 à 3). --- ## Quand utiliser quelle méthode - **Tests rapides et scripts ponctuels** → paramètre de requête (`?apiKey=`). Le plus rapide à saisir, fonctionne dans un navigateur. - **Intégrations en production et appels serveur à serveur** → `X-API-Key` ou `Authorization: Bearer YOUR_API_KEY`. Permet de garder la clé hors des URL et des journaux. - **Applications propriétaires avec un utilisateur Your AI Connector connecté** → `Authorization: Bearer `. --- ## Portées des clés Votre compte possède une **clé API principale** — celle située sous **Paramètres → Intégrations → Clé API**. Elle dispose d'un accès complet à toutes les fonctionnalités du compte. Vous pouvez également créer des **clés à portée limitée** : des clés nommées qui n'accèdent qu'aux parties de l'API que vous choisissez, par exemple une clé en lecture seule limitée aux analyses pour un tableau de bord de reporting. Une clé à portée limitée s'utilise exactement comme la clé principale (l'une des méthodes 1 à 3 ci-dessus), mais ses autorisations sont vérifiées à chaque requête : - **En dehors de ses zones autorisées, elle est refusée.** Une écriture avec une clé en lecture seule, ou un appel vers une section pour laquelle la clé n'a pas été autorisée, renvoie une erreur `403` — `key_read_only` ou `key_scope_denied` dans le champ `error_code`. La vérification est délibérément stricte : tout ce qui n'est pas clairement inclus dans les zones autorisées de la clé est refusé plutôt que laissé passer. Si vous voyez l'une de ces `403`, c'est que la clé ne couvre tout simplement pas ce point de terminaison. - **Elle possède son propre budget de limitation de débit.** Une clé à portée limitée est comptabilisée séparément de votre clé principale ; ainsi, un tableau de bord très sollicité utilisant une clé à portée limitée ne peut pas épuiser le quota dont dépendent vos autres intégrations. Vous choisissez ce budget par minute lors de la création de la clé. - **Elle ne peut pas gérer les clés API.** Seul le propriétaire du compte — connecté ou utilisant la clé principale — peut lister, créer, modifier, renouveler ou révoquer des clés. Une clé à portée limitée ne peut jamais générer une clé plus étendue. Consultez [Clés API](api-keys.md) pour savoir comment créer, modifier et révoquer des clés à portée limitée. --- ## Le verrouillage des fonctionnalités payantes L'accès à l'API est une fonctionnalité payante. Lorsque votre forfait ne l'inclut pas, une requête avec une clé par ailleurs valide est rejetée avec `403` : ```json { "success": false, "error_code": 403, "error": "This action requires the \"api_access\" feature, which is not enabled for this account." } ``` If you see this, check your plan or contact [hi@youraiconnector.com](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead: ```json { "success": false, "error_code": 401, "error": "Invalid API key" } ``` --- ## Garder votre clé en sécurité - **Traitez la clé comme un mot de passe.** Votre clé principale donne un accès complet à votre compte. Si vous devez confier une clé à un outil ou à une personne qui n'a besoin que d'une partie de ses accès, créez plutôt une clé à portée limitée — voir [Portées des clés](#key-scopes). - **Gardez-la côté serveur.** Ne l'intégrez jamais dans du JavaScript côté navigateur, dans un bundle d'application mobile ou dans tout code pouvant être lu par un utilisateur final. - **Stockez-la dans un gestionnaire de secrets** ou dans une configuration côté serveur, et non dans le contrôle de version. - **Renouvelez-la en cas de fuite.** Générez une nouvelle clé depuis le tableau de bord ou appelez `POST https://api.youraiconnector.com/v1/api-keys/rotate` — cela invalide immédiatement l'ancienne. Voir [Clés API](api-keys.md). - **Utilisez toujours HTTPS** afin que la clé soit chiffrée pendant le transfert. --- ## Étapes suivantes - [Démarrage](getting-started.md) — votre première requête et les guides de ressources. - [Erreurs et pagination](errors-and-pagination.md) — gérez les échecs et parcourez les résultats par page. - [Clés API](api-keys.md) — renouvelez, révoquez et vérifiez l'utilisation de votre clé.