# API des clés API Ces points de terminaison vous permettent de gérer les clés API de votre compte par le biais du code. Ils opèrent tous uniquement sur les clés du compte appelant. Il existe deux types de clés, et elles se trouvent sur des chemins distincts : - **Votre clé principale** — la clé unique à accès complet située sous **Paramètres → Intégrations → Clé API**. Consultez son aperçu masqué, vérifiez votre utilisation des limites de débit, faites-la pivoter ou révoquez-la. Il s'agit des points de terminaison `/api-keys/current`, `/api-keys/rotate` et `/api-keys/usage` ci-dessous. - **Clés à portée limitée (Scoped keys)** — des clés supplémentaires nommées que vous créez pour une tâche spécifique, chacune étant limitée aux parties de l'API que vous choisissez. Il s'agit des points de terminaison `/api-keys` et `/api-keys/{id}` sous [Clés à portée limitée](#scoped-keys). Rien ne change concernant votre clé principale lorsque vous en créez une ; les intégrations existantes continuent de fonctionner sans modification. Tous les chemins ci-dessous sont relatifs à l'URL de base de l'API : ``` https://api.youraiconnector.com/v1 ``` Chaque requête doit être authentifiée. Consultez [Authentification](authentication.md) pour connaître les quatre méthodes acceptées. Les exemples ici utilisent l'en-tête `X-API-Key` (et une forme de paramètre de requête pour cURL). > **Lisez ceci en premier.** Le renouvellement ou la révocation de votre clé prend effet **immédiatement**. Dès que l'un de ces appels réussit, l'ancienne clé cesse de fonctionner — chaque intégration qui l'utilise encore commencera à recevoir des erreurs `401`. Prévoyez-le : effectuez le renouvellement pendant une fenêtre de maintenance et mettez à jour toutes vos intégrations immédiatement. --- ## Obtenir les métadonnées de la clé actuelle Renvoie votre clé active : la clé complète dans `api_key` lorsqu'une copie récupérable existe, un aperçu masqué (les 4 premiers et les 4 derniers caractères) et, lorsqu'elle est disponible, la date de sa création. `api_key` est `null` pour les clés créées avant que les copies récupérables ne soient conservées — effectuez une rotation une fois et la nouvelle clé pourra être affichée à nouveau ultérieurement. `GET /api-keys/current` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Réponse** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "api_key_masked": "abcd...qrst", "created_at": "2026-06-01T10:00:00.000Z" } ``` Si le compte n'a pas de clé API, la réponse est `404` avec `{ "success": false, "error": "No API key found for this account" }`. --- ## Obtenir l'utilisation de la limite de débit Renvoie votre utilisation de la limite de débit pour la fenêtre actuelle : la limite de requêtes par fenêtre, combien de requêtes ont été comptabilisées jusqu'à présent, combien il en reste et quand la fenêtre se réinitialise. Utilisez ceci pour créer une limitation côté client afin que votre intégration ralentisse avant d'atteindre les réponses `429`. `GET /api-keys/usage` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/usage" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/usage", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Réponse** ```json { "success": true, "usage": { "limit": 300, "window_seconds": 60, "used": 37, "remaining": 263, "window_resets_at": "2026-06-09T12:01:00.000Z" } } ``` Si aucune requête n'a encore été enregistrée dans la fenêtre actuelle, l'utilisation est signalée comme nulle et la réponse inclut un champ `note` expliquant pourquoi. --- ## Renouveler la clé Génère une nouvelle clé API et invalide la précédente en une seule étape. Utilisez ceci si vous suspectez que votre clé a été divulguée, ou dans le cadre d'une politique régulière de renouvellement des identifiants. `POST /api-keys/rotate` > **La nouvelle clé n'est affichée qu'une seule fois.** Elle est renvoyée dans cette réponse et ne pourra plus être récupérée intégralement par la suite — stockez-la en toute sécurité dès que vous la recevez. L'ancienne clé cesse de fonctionner dès que cet appel réussit, mettez donc à jour toutes les intégrations qui l'utilisaient. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys/rotate", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Réponse** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again." } ``` --- ## Révoquer la clé Supprime définitivement la clé API de votre compte. La révocation est immédiate : toute requête ultérieure utilisant la clé révoquée — y compris les intégrations telles que Make, Zapier ou des scripts personnalisés — est rejetée avec une erreur `401`. Pour rétablir l'accès à l'API par la suite, générez une nouvelle clé depuis les paramètres de votre compte tout en étant connecté à l'application. `DELETE /api-keys/current` > **Il n'y a pas d'annulation possible.** Contrairement à la rotation, la révocation ne vous fournit pas de clé de remplacement. Ne révoquez la clé que si vous avez l'intention de stopper l'accès à l'API (par exemple, en cas de fuite d'une clé que vous ne pouvez pas remplacer immédiatement). **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.delete( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Réponse** ```json { "success": true, "revoked": true, "message": "API key revoked. All requests using it will be rejected immediately." } ``` Si le compte ne possède aucune clé à révoquer, la réponse est `404`. --- ## Clés à portée limitée Une clé à portée limitée est une clé API supplémentaire que vous créez pour une tâche spécifique, ne disposant que des accès nécessaires à cette tâche. Le cas classique : vous souhaitez connecter un tableau de bord client, un outil de reporting ou un script interne à votre compte sans fournir une clé qui pourrait également envoyer des messages, modifier vos agents IA ou acheter un numéro de téléphone. La restriction accompagne la clé elle-même, de sorte que quiconque la détient ne peut faire que ce que vous avez autorisé lors de sa création. **Ce que vous pouvez restreindre** | Champ | Signification | |---|---| | `read_only` | `true` (par défaut) signifie que seules les requêtes en lecture sont autorisées. Toute création, mise à jour ou suppression est refusée. | | `tags` | La liste des sections de l'API que la clé peut utiliser, écrite avec les mêmes noms de section que ceux que vous voyez dans cette documentation et dans l'[explorateur d'API](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, etc. Une liste vide signifie toutes les sections. | | `sub_account_ids` | Les comptes gérés sur lesquels la clé peut agir. Vide signifie uniquement votre propre compte ; `["*"]` signifie tout compte que vous gérez réellement. La propriété est toujours vérifiée à chaque requête. | | `rate_limit_per_min` | Requêtes par minute pour cette clé, comptabilisées dans son propre budget afin qu'elle ne puisse pas épuiser le quota de vos autres intégrations. La valeur par défaut est `60`, et elle ne peut pas être définie au-dessus de `300`. | Vous pouvez également donner à une clé une date d'`expires_at` (ISO 8601, et elle doit être dans le futur). Après ce moment, la clé cesse de fonctionner d'elle-même. Si vous ne la définissez pas, la clé n'expire jamais jusqu'à ce que vous la révoquiez. > **Les refus sont fermés par défaut.** Si une requête sort du cadre autorisé par la clé, elle est refusée plutôt que laissée passer : une écriture avec une clé en lecture seule renvoie `403` avec `error_code: "key_read_only"`, et toute action en dehors des sections autorisées de la clé renvoie `403` avec `error_code: "key_scope_denied"`. Si une clé à portée limitée reçoit une erreur `403` inattendue, le point de terminaison que vous avez appelé ne fait tout simplement pas partie de ses portées — élargissez la portée de la clé ou utilisez votre clé principale. > **Seul le propriétaire du compte gère les clés.** Ces quatre points de terminaison nécessitent votre clé principale ou une session propriétaire dans l'application. Une clé à portée limitée ne peut jamais lister, créer, modifier ou révoquer des clés — y compris elle-même — de sorte qu'une clé restreinte ne peut jamais être utilisée pour en créer une plus large. Essayer renvoie `403` avec `error_code: "key_scope_denied"`. Pour la même raison, `API Keys` n'est pas une section que vous pouvez accorder : demander cela renvoie `400` avec `error_code: "invalid_scopes"`. ### Lister les clés à portée limitée Renvoie les clés à portée limitée du compte, de la plus récente à la plus ancienne (jusqu'à 200), y compris celles révoquées afin que vous puissiez voir ce qui a été retiré et quand. Seuls des aperçus masqués sont renvoyés — la valeur d'une clé à portée limitée n'est affichée qu'une seule fois, lors de la création, et n'est jamais récupérable par la suite. `GET /api-keys` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" ``` **Réponse** ```json { "success": true, "api_keys": [ { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } ] } ``` ### Créer une clé à portée limitée Crée une nouvelle clé délimitée et renvoie sa valeur **une seule fois**. `POST /api-keys` > **La clé n'est affichée qu'une seule fois.** Elle figure dans cette réponse et nulle part ailleurs, jamais — il n'y a aucun moyen de la consulter à nouveau par la suite. Stockez-la dès que vous la recevez. Si vous la perdez, révoquez-la et créez-en une autre. **Champs du corps de la requête** — tous facultatifs : | Champ | Type | Notes | |---|---|---| | `label` | string | Votre propre nom pour la clé, affiché dans la liste et dans les Paramètres. | | `scopes` | object | Les quatre champs du tableau ci-dessus. Omettez l'objet entier pour obtenir la valeur par défaut sécurisée : lecture seule, limitée à `Analytics`, votre propre compte uniquement, 60 requêtes par minute. | | `expires_at` | date ISO 8601 | Date d'expiration facultative, doit être dans le futur. | **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 } }' ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ label: "Client dashboard - Acme", scopes: { read_only: true, tags: ["Analytics"] }, }), }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "label": "Client dashboard - Acme", "scopes": {"read_only": True, "tags": ["Analytics"]}, }, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Réponse** — `201 Created` ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "revoked": false }, "message": "Store this key now — it is shown once and cannot be retrieved again." } ``` Quelques détails à connaître lors de votre développement : - **Omettre `scopes` n'est pas la même chose que d'envoyer une liste `tags` vide.** Laissez `scopes` de côté pour obtenir la valeur par défaut sécurisée (lecture seule, `Analytics` uniquement). Envoyez `"tags": []` intentionnellement et la clé pourra utiliser toutes les sections — cela est interprété comme une demande délibérée pour une clé sans restriction. - **`read_only` reste `true` à moins que vous n'envoyiez explicitement `false`.** Une faute de frappe ou un indicateur manquant ne peut jamais produire accidentellement une clé disposant de droits d'écriture. ### Mettre à jour une clé délimitée Modifie l'étiquette, les portées et/ou l'expiration d'une clé. Envoyez n'importe quelle combinaison des trois ; l'envoi d'aucun d'entre eux renvoie `400`. `PATCH /api-keys/{id}` Le `{id}` est l'identifiant `id` de la clé dans la liste (la valeur `key_...`), jamais la clé elle-même. > **Les portées sont remplacées, pas fusionnées.** Tout ce que vous envoyez devient l'ensemble complet des autorisations de la clé. C'est délibéré : restreindre une clé ne peut jamais laisser silencieusement en place l'ancien accès plus large. Envoyez toujours l'objet `scopes` complet que vous souhaitez, et non seulement le champ que vous modifiez. La valeur de la clé ne change jamais. Il n'y a pas de rotation sur place pour une clé délimitée — pour en renouveler une, créez une nouvelle clé et révoquez l'ancienne, afin que l'accès d'une information d'identification ne puisse jamais changer sous une intégration qui la détient toujours. **cURL** ```bash curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme (read-only)", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 } }' ``` **Réponse** ```json { "success": true, "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme (read-only)", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } } ``` S'il n'y a aucune clé avec cet identifiant sur votre compte, la réponse est `404`. ### Révoquer une clé à portée limitée La révocation est immédiate : la toute prochaine requête utilisant cette clé sera rejetée avec une `401`. Votre clé principale et toutes les autres clés à portée limitée ne sont pas affectées. `DELETE /api-keys/{id}` La clé reste dans votre liste marquée comme `"revoked": true`, vous conservez donc une trace de ce qui existait et de ce à quoi elle pouvait accéder. La révocation d'une clé déjà révoquée réussit et ne change rien. **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" ``` **Réponse** ```json { "success": true, "revoked": true, "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "message": "API key revoked. All requests using it will be rejected immediately." } ``` --- ## Erreurs de l'API des clés d'API Les points de terminaison des clés d'API renvoient l'enveloppe d'erreur standard : ```json { "success": false, "error": "No API key found for this account" } ``` Sur un point de terminaison de clé d'API, une clé manquante ou invalide renvoie `401` et un compte sans clé enregistrée renvoie `404`. Les codes partagés que chaque point de terminaison peut renvoyer — `400`, `403` (votre forfait n'inclut pas l'accès à l'API), `429` (limite de débit) et `500` — sont répertoriés avec des conseils de nouvelle tentative dans [Erreurs et pagination](errors-and-pagination.md). Les points de terminaison des clés à portée limitée ajoutent quelques codes nommés dans le champ `error_code` afin que vous puissiez distinguer les cas : | `error_code` | Statut | Ce qui s'est passé | |---|---|---| | `key_read_only` | `403` | Une clé en lecture seule a tenté une opération d'écriture. | | `key_scope_denied` | `403` | La clé n'est pas autorisée sur ce point de terminaison ou ce compte géré — ou une clé à portée limitée a tenté de gérer des clés API, ce qui n'est jamais autorisé. | | `invalid_scopes` | `400` | Les portées demandées incluaient la section `API Keys`. Les clés ne peuvent pas gérer d'autres clés. | | `404` | `404` | Aucune clé avec cet identifiant sur votre compte. | --- ## Étapes suivantes - [Authentification](authentication.md) — les quatre méthodes pour authentifier une requête et comment les portées des clés sont appliquées. - [Erreurs et limites de débit](errors-and-pagination.md) — codes de statut et limite de 300 requêtes/min.