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 ci-dessous. Pour générer une clé, consultez Accès API.

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 #

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

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

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

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

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

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

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 <Firebase ID token>

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 <Firebase ID token>.

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

{
  "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. A missing or wrong key returns 401 instead:

{
  "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.
• 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.
• Utilisez toujours HTTPS afin que la clé soit chiffrée pendant le transfert.

Étapes suivantes #

• Démarrage — votre première requête et les guides de ressources.
• Erreurs et pagination — gérez les échecs et parcourez les résultats par page.
• Clés API — renouvelez, révoquez et vérifiez l’utilisation de votre clé.