Authentification et clés API

L’API Discuse authentifie chaque requête au moyen d’une clé API. Envoyez-la dans l’en-tête de requête X-API-Key (ou sous forme de champ api_key dans le corps JSON). Les clés commencent par le préfixe disc_, sont associées à un seul projet et ne sont affichées intégralement qu’une seule fois, lors de leur création. Ce guide explique comment les obtenir, les utiliser, les sécuriser et les renouveler.

Comment fonctionne l’authentification Discuse ?

Chaque appel API doit inclure une clé API valide. Discuse l’utilise pour :

Suivre l’utilisation par rapport au quota de votre projet
Appliquer une limitation de débit par clé afin d’éviter les abus
Associer les requêtes au bon projet et à ses paramètres
Contrôler l’accès aux ressources de votre compte

Obtenir votre clé API

Étape 1 : Créer un compte

Si ce n’est pas déjà fait, créez un compte Discuse sur discuse.com. Vous pouvez commencer avec l’offre gratuite Basic, qui inclut un quota mensuel de requêtes API ainsi que l’accès aux vérifications de texte, de spam, de langue et d’images. Consultez la page des tarifs pour connaître les limites actuelles de chaque offre.

Étape 2 : Accéder au tableau de bord

Après vous être connecté, accédez à votre tableau de bord. Recherchez la section "API Keys" ou "Developer" dans le menu de navigation.

Étape 3 : Générer une nouvelle clé

Cliquez sur "Create New API Key" et ajoutez éventuellement un nom ou une description à la clé. Cela vous aidera à identifier l’usage de chaque clé si vous en créez plusieurs.

Votre nouvelle clé API ne sera affichée qu’une seule fois. Copiez-la immédiatement et conservez-la en lieu sûr : vous ne pourrez plus afficher la clé complète par la suite.

Utiliser votre clé API

Incluez votre clé API dans l’en-tête X-API-Key de chaque requête :

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

Vous pouvez aussi transmettre la clé sous forme de champ api_key dans le corps JSON au lieu de l’en-tête — l’en-tête est recommandé afin que la clé ne se retrouve jamais dans les journaux des corps de requête.

Exemple JavaScript

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Exemple Python

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

Bonnes pratiques de sécurité pour les clés API

N’exposez jamais les clés dans le code côté client

Les clés API ne doivent jamais être incluses dans du JavaScript exécuté dans le navigateur. Le code côté client est visible par toute personne qui consulte le code source de votre page.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Utilisez des variables d’environnement

Stockez les clés API dans des variables d’environnement, et non dans votre base de code :

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Renouvelez régulièrement les clés

Renouvelez périodiquement vos clés API, en particulier si vous pensez qu’elles ont pu être compromises :

Générez une nouvelle clé API
Mettez à jour votre application pour utiliser la nouvelle clé
Vérifiez que tout fonctionne correctement
Révoquez l’ancienne clé

Remarque : une clé révoquée peut rester utilisable pendant environ 5 minutes, car les clés validées sont mises en cache. Prévoyez donc ce court chevauchement lors des rotations, plutôt que de compter sur un basculement instantané.

Utilisez des clés distinctes pour les différents environnements

Créez des clés API différentes pour le développement, la préproduction et la production :

Environnement	Objectif de la clé
Développement	Tests et développement local
Préproduction	Tests avant production
Production	Trafic de l’application en conditions réelles

Cela vous permet de révoquer une clé compromise sans affecter les autres environnements.

Comment fonctionne la limitation de débit ?

La limitation de débit s’applique par clé API, et non par offre. Chaque clé possède une limite de requêtes par minute (RPM) définie lors de sa création ; si vous n’en spécifiez pas, elle est fixée par défaut à 60 requêtes par minute. Différentes clés d’un même compte peuvent avoir des limites différentes, ce qui vous permet d’attribuer un RPM plus élevé à un service à fort volume qu’à une intégration ponctuelle.

Lorsqu’une clé dépasse sa limite RPM, la requête échoue avec un statut HTTP 429 Too Many Requests, dont le champ message indique que la limite de débit a été dépassée. Les compteurs de limitation de débit sont réinitialisés sur une fenêtre glissante d’une minute.

Gérer les limites de débit

Patientez puis réessayez en cas de 429 (ainsi qu’en cas de 5xx transitoire). Comme la fenêtre est d’une minute, une temporisation exponentielle qui démarre autour d’une seconde puis augmente fonctionne bien :

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

Quelles réponses d’erreur puis-je recevoir ?

Situation	Statut HTTP
Requête mal formée (contenu vide, texte de plus de 10 000 caractères, trop d’URL)	validation de requête `400`
Clé API manquante ou invalide	`401`
Limite de débit dépassée pour la clé	`429`
Quota de la période de facturation épuisé	`200` avec un `message` et `usage` (pas un statut d’erreur)

L’épuisement du quota n’est volontairement pas une erreur HTTP : la réponse /api/v2/check renvoie tout de même 200 avec has_violations: false, un message décrivant le quota épuisé, ainsi qu’un objet usage indiquant api_requests_remaining: 0. Examinez ces champs plutôt que de vous fier à un code de statut. Les échecs d’authentification renvoient 401, les limites de débit 429 et les échecs de validation de requête 400. Consultez la référence Codes d’erreur et de réponse pour obtenir la liste complète.

Gérer plusieurs clés

Pour les grandes équipes ou les applications complexes, vous pouvez avoir besoin de plusieurs clés API :

Cas d’utilisation de plusieurs clés

Clés par environnement : clés distinctes pour le développement, la préproduction et la production
Clés par service : clés différentes pour différents microservices
Clés par équipe : isolation de l’utilisation par équipe pour la facturation interne
Clés temporaires : clés à durée de vie courte pour des prestataires ou des intégrations

Bonnes pratiques de gestion des clés

Nommez les clés de manière descriptive : "Production - User Service", "Staging - Backend"
Documentez l’utilisation des clés : tenez à jour la liste des endroits où chaque clé est utilisée
Configurez des alertes : surveillez les schémas d’utilisation inhabituels
Effectuez des audits réguliers : examinez et supprimez les clés inutilisées chaque trimestre

Étapes suivantes

Guide de démarrage rapide - Effectuer votre premier appel API
Analyse de texte - En savoir plus sur la détection de sentiment
Mise à l’échelle de la modération de contenu - Modèles d’implémentation à fort volume