Hoe authenticeer ik verzoeken?

Alle verzoeken aan de Cathopic API moeten worden geauthenticeerd met je API-sleutel. Zo authenticeer je je API-aanroepen correct.

Authenticatiemethode

De Cathopic API gebruikt API-sleutel-authenticatie via HTTP-headers:

• Naam van de header: x-api-key

• Waarde van de header: Je volledige API-sleutel

• Vereist voor: Alle API-endpoints

• Hoofdlettergevoelig: Headernamen en -waarden moeten exact overeenkomen

Voorbeeld van basis-authenticatie

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):

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

Authenticatiefouten

Als authenticatie mislukt, ontvang je een foutmelding:

Ontbrekende API-sleutel:

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

Ongeldige API-sleutel:

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

Inactieve API-sleutel:

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

Belangrijke herinneringen

Beveiliging:

• Nooit API-sleutels hardcoderen: Gebruik omgevingsvariabelen of een veilige configuratie

• Alleen server-side: Neem nooit API-sleutels op in client-side JavaScript

• Gebruik alleen HTTPS: API-sleutels die via HTTP worden verzonden zijn kwetsbaar

• Regelmatig roteren: Wijzig sleutels periodiek voor de veiligheid

Foutafhandeling:

• Controleer statuscodes: Controleer altijd de HTTP-responsstatus

• Log authenticatiefouten: Houd mislukte pogingen bij voor beveiligingsmonitoring

• Implementeer retry-logica: Met exponential backoff voor tijdelijke fouten

• Valideer vóór verzending: Zorg dat de API-sleutel correct is geladen

Authenticatie testen

Snelle test om te controleren of je API-sleutel werkt:

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

Verwachte respons (succes):

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

Veelgemaakte fouten

• Verkeerde headernaam: Moet zijn x-api-key, niet api-key of Authorization

• Onjuist formaat van de waarde: Gebruik de volledige sleutel zoals die is, zonder "Bearer"-prefix

• Achterblijvende spaties: Knip API-sleutelwaarden bij voordat je ze gebruikt

• Sleutel niet geladen: Controleer of de omgevingsvariabele correct is ingesteld

Voor het oplossen van authenticatieproblemen, zie "Common authentication errors" in deze sectie.