Comment authentifier les requêtes ?

Toutes les requêtes adressées à l’API Cathopic doivent être authentifiées à l’aide de votre clé API. Voici comment authentifier correctement vos appels API.

Méthode d’authentification

L’API Cathopic utilise une authentification par clé API via des en-têtes HTTP :

• Nom de l’en-tête : x-api-key

• Valeur de l’en-tête : Votre clé API complète

• Requis pour : Tous les endpoints de l’API

• Sensible à la casse : Les noms et valeurs des en-têtes doivent correspondre exactement

Exemple d’authentification de base

cURL :

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Virgin Mary",
    "page": 1,
    "page_size": 20,
    "order": "popular"
  }'

JavaScript (fetch) :

const response = await fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CATHOPIC_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Virgin Mary',
    page: 1,
    page_size: 20,
    order: 'popular'
  })
});
const data = await response.json();
console.log(data);

JavaScript (axios) :

const axios = require('axios');
const response = await axios.post(
  'https://api.cathopic.com/resources',
  {
    query: 'Virgin Mary',
    page: 1,
    page_size: 20,
    order: 'popular'
  },
  {
    headers: {
      'x-api-key': process.env.CATHOPIC_API_KEY
    }
  }
);
console.log(response.data);

Python (requests) :

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'query': 'Virgin Mary',
        'page': 1,
        'page_size': 20,
        'order': 'popular'
    }
)
data = response.json()
print(data)

PHP (cURL) :

<?php $apiKey = getenv('CATHOPIC_API_KEY');
$ch = curl_init('https://api.cathopic.com/resources');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'query' => 'Virgin Mary',
    'page' => 1,
    'page_size' => 20,
    'order' => 'popular'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
?>

Erreurs d’authentification

Si l’authentification échoue, vous recevrez une réponse d’erreur :

Clé API manquante :

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Clé API invalide :

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Clé API inactive :

HTTP 401 Unauthorized
{
  "error": "Unauthorized token"
}

Rappels importants

Sécurité :

• Ne jamais coder en dur les clés API : Utilisez des variables d’environnement ou une configuration sécurisée

• Côté serveur uniquement : Ne mettez jamais les clés API dans du JavaScript côté client

• Utilisez uniquement HTTPS : Les clés API transmises via HTTP sont vulnérables

• Faites tourner régulièrement les clés : Changez les clés périodiquement pour la sécurité

Gestion des erreurs :

• Vérifiez les codes de statut : Contrôlez toujours le statut de la réponse HTTP

• Journalisez les échecs d’authentification : Suivez les tentatives échouées pour le suivi de la sécurité

• Implémentez une logique de relance : Avec un backoff exponentiel pour les erreurs transitoires

• Validez avant l’envoi : Assurez-vous que la clé API est chargée correctement

Tester l’authentification

Test rapide pour vérifier que votre clé API fonctionne :

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "page": 1, "page_size": 1}'

Réponse attendue (succès) :

{
  "total": 1234,
  "page": 1,
  "page_size": 1,
  "results": [ ... ]
}

Erreurs courantes

• Mauvais nom d’en-tête : Doit être x-api-key, et non api-key ou Authorization

• Format de valeur incorrect : Utilisez la clé complète telle quelle, sans préfixe « Bearer »

• Espace en trop : Supprimez les espaces en fin de valeur de la clé API avant de l’utiliser

• Clé non chargée : Vérifiez que la variable d’environnement est correctement définie

Pour résoudre les problèmes d’authentification, consultez « Common authentication errors » dans cette section.