¿Cómo autent ico las peticiones?

Todas las peticiones a la API de Cathopic deben estar autenticadas usando tu clave API. Aquí está cómo autenticar correctamente tus llamadas a la API.

Método de autenticación

La API de Cathopic usa autenticación por clave API vía headers HTTP:

• Nombre del header: x-api-key

• Valor del header: Tu clave API completa

• Requerido para: Todos los endpoints de la API

• Sensible a mayúsculas: Los nombres y valores de headers deben coincidir exactamente

Ejemplo básico de autenticación

cURL:

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Virgen María",
    "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: 'Virgen María',
    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: 'Virgen María',
    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': 'Virgen María',
        'page': 1,
        'page_size': 20,
        'order': 'popular'
    }
)
data = response.json()
print(data)

PHP (cURL):

 'Virgen María',
    'page' => 1,
    'page_size' => 20,
    'order' => 'popular'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
?>

Errores de autenticación

Si la autenticación falla, recibirás una respuesta de error:

Clave API faltante:

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

Clave API inválida:

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

Clave API inactiva:

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

Recordatorios importantes

Seguridad:

• Nunca hardcodees claves API: Usa variables de entorno o configuración segura

• Solo del lado del servidor: Nunca incluyas claves API en JavaScript del lado del cliente

• Usa solo HTTPS: Las claves API transmitidas por HTTP son vulnerables

• Rota regularmente: Cambia las claves periódicamente por seguridad

Manejo de errores:

• Verifica códigos de estado: Siempre verifica el estado de respuesta HTTP

• Registra fallos de autenticación: Rastrea intentos fallidos para monitoreo de seguridad

• Implementa lógica de reintento: Con retroceso exponencial para errores transitorios

• Valida antes de enviar: Asegura que la clave API se carga correctamente

Probar autenticación

Prueba rápida para verificar que tu clave API funciona:

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

Respuesta esperada (éxito):

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

Errores comunes

• Nombre de header incorrecto: Debe ser x-api-key, no api-key o Authorization

• Formato de valor incorrecto: Usa la clave completa tal cual, sin prefijo "Bearer"

• Espacio en blanco al final: Recorta los valores de clave API antes de usar

• Clave no cargada: Verifica que la variable de entorno esté correctamente configurada

Para solucionar problemas de autenticación, consulta "Errores comunes de autenticación" en esta sección.