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. 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 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

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

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

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

{
  "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

curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"

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

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

{
  "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

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

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

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

{
  "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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"

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

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

{
  "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

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

curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse

{
  "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 :

cURL

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

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

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

{
  "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

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

{
  "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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse

{
  "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 :

{
  "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.

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 :

Étapes suivantes #

• Authentification — 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 — codes de statut et limite de 300 requêtes/min.