Como autenticar as requisições?

Todas as requisições para a API Cathopic devem ser autenticadas usando sua chave de API. Veja como autenticar corretamente suas chamadas de API.

Método de autenticação

A API Cathopic usa autenticação por chave de API via cabeçalhos HTTP:

• Nome do cabeçalho: x-api-key

• Valor do cabeçalho: Sua chave de API completa

• Obrigatório para: Todos os endpoints da API

• Diferencia maiúsculas de minúsculas: Os nomes e valores dos cabeçalhos devem corresponder exatamente

Exemplo de autenticação básica

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);
?>

Erros de autenticação

Se a autenticação falhar, você receberá uma resposta de erro:

Chave de API ausente:

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

Chave de API inválida:

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

Chave de API inativa:

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

Lembretes importantes

Segurança:

• Nunca codifique chaves de API no código: Use variáveis de ambiente ou configuração segura

• Apenas no lado do servidor: Nunca inclua chaves de API em JavaScript do lado do cliente

• Use apenas HTTPS: Chaves de API transmitidas via HTTP são vulneráveis

• Gire regularmente: Altere as chaves periodicamente para segurança

Tratamento de erros:

• Verifique os códigos de status: Sempre confirme o status da resposta HTTP

• Registre falhas de autenticação: Acompanhe tentativas malsucedidas para monitoramento de segurança

• Implemente lógica de nova tentativa: Com backoff exponencial para erros transitórios

• Valide antes de enviar: Garanta que a chave de API foi carregada corretamente

Testando a autenticação

Teste rápido para verificar se sua chave de API funciona:

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

Resposta esperada (sucesso):

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

Erros comuns

• Nome do cabeçalho incorreto: Deve ser x-api-key, não api-key ou Authorization

• Formato de valor incorreto: Use a chave completa como está, sem prefixo "Bearer"

• Espaço em branco no final: Remova espaços em branco dos valores da chave de API antes de usar

• Chave não carregada: Verifique se a variável de ambiente está definida corretamente

Para solucionar problemas de autenticação, veja "Common authentication errors" nesta seção.