Come faccio ad autenticare le richieste?

Tutte le richieste all’API di Cathopic devono essere autenticate utilizzando la tua chiave API. Ecco come autenticare correttamente le chiamate alla tua API.

Metodo di autenticazione

L’API di Cathopic utilizza l’autenticazione tramite chiave API tramite intestazioni HTTP:

• Nome dell’intestazione: x-api-key

• Valore dell’intestazione: La tua chiave API completa

• Richiesto per: Tutti gli endpoint dell’API

• Maiuscole/minuscole: I nomi e i valori delle intestazioni devono corrispondere esattamente

Esempio di autenticazione di 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);
?>

Errori di autenticazione

Se l’autenticazione non riesce, riceverai una risposta di errore:

Chiave API mancante:

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

Chiave API non valida:

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

Chiave API inattiva:

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

Promemoria importanti

Sicurezza:

• Non inserire mai chiavi API nel codice: Usa variabili d’ambiente o configurazioni sicure

• Solo lato server: Non includere mai chiavi API in JavaScript lato client

• Usa solo HTTPS: Le chiavi API trasmesse via HTTP sono vulnerabili

• Ruota regolarmente le chiavi: Cambiale periodicamente per la sicurezza

Gestione degli errori:

• Controlla i codici di stato: Verifica sempre lo stato della risposta HTTP

• Registra gli errori di autenticazione: Tieni traccia dei tentativi non riusciti per il monitoraggio della sicurezza

• Implementa la logica di retry: Con backoff esponenziale per errori temporanei

• Verifica prima di inviare: Assicurati che la chiave API sia caricata correttamente

Test dell’autenticazione

Test rapido per verificare che la tua chiave API funzioni:

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}'

Risposta attesa (successo):

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

Errori comuni

• Nome dell’intestazione errato: Deve essere x-api-key, non api-key o Authorization

• Formato del valore non corretto: Usa la chiave completa così com’è, senza prefisso "Bearer"

• Spazi bianchi finali: Rimuovi gli spazi bianchi dai valori della chiave API prima di usarli

• Chiave non caricata: Controlla che la variabile d’ambiente sia impostata correttamente

Per la risoluzione dei problemi di autenticazione, vedi "Errori comuni di autenticazione" in questa sezione.