Authenticatie & API Keys

Alle verzoeken aan de Sidefish REST API vereisen geldige authenticatie. Sidefish ondersteunt twee primaire authenticatiemethoden voor integraties: API Keys voor directe server-naar-server koppelingen en OAuth 2.0 Bearer Tokens voor externe applicaties en gebruikerssessies.

---

1. Authenticatiemethoden

Methode	HTTP Header	Gebruiksscenario
API Key	x-api-key: <api_key>	Server-to-server automatisaties, batch-scripts en directe CRM-koppelingen.
OAuth 2.0 Bearer	Authorization: Bearer <token>	Externe partnerapplicaties (zoals BrokerCloud) en softwarekoppelingen van derden.

---

2. Werken met API Keys

Een API Key is gekoppeld aan een specifiek gebruikersaccount binnen uw organisatie. Alle acties die via de API worden uitgevoerd (zoals het aanmaken van een klant of het versturen van een actie) worden gelogd onder de identiteit van deze gebruiker.

API Key Genereren of Raadplegen

1. Log in op de beheeromgeving van Sidefish.
2. Navigeer naar Gebruikers en open het gewenste service- of medewerkersaccount.
3. In de sectie Sidefish API vindt u de actieve API Key.
4. Kopieer de sleutel en bewaar deze veilig in uw secrets manager of .env-configuratie.

[!CAUTION] Een API-sleutel geeft directe toegang tot de gegevens van uw organisatie. Deel deze sleutel nooit publiekelijk in frontend-code (zoals React of Vue) of openbare repositories.

Request Headers

Voeg de x-api-key header toe aan elk uitgaand HTTP-verzoek:

GET /api/v1/customers HTTP/1.1
Host: sidefish.app
x-api-key: sf_live_9a8b7c6d5e4f3g2h1i0j
Content-Type: application/json
Accept: application/json

---

3. Rechten & Multi-Tenancy

• Organisatiegrenzen: Een API-sleutel heeft uitsluitend toegang tot de data van de eigen organisatie. Toegang tot dossiers of klanten van andere organisaties wordt op databaseniveau geblokkeerd.
• Gebruikersrollen: De API-sleutel erft automatisch de bevoegdheden van de gekoppelde gebruikersgroepen (bijvoorbeeld administrator, dossierbeheerder of alleen-lezen).
• CSRF-vrijstelling: Voor server-naar-server verzoeken met een geldige x-api-key wordt browser-specifieke CSRF-validatie automatisch overgeslagen.

---

4. Codevoorbeelden

cURL

curl -X GET "https://sidefish.app/api/v1/customers?limit=10" \
  -H "x-api-key: JOUW_API_SLEUTEL" \
  -H "Content-Type: application/json"

Node.js (Fetch / TypeScript)

const SIDEFISH_API_URL = "https://sidefish.app/api/v1";
const API_KEY = process.env.SIDEFISH_API_KEY!;

async function fetchCustomers() {
  const response = await fetch(`${SIDEFISH_API_URL}/customers?limit=25`, {
    method: "GET",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
  });

  if (!response.ok) {
    throw new Error(`API fout [${response.status}]: ${response.statusText}`);
  }

  const data = await response.json();
  return data;
}

Python (Requests)

import os
import requests

API_URL = "https://sidefish.app/api/v1"
API_KEY = os.environ.get("SIDEFISH_API_KEY")

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.get(f"{API_URL}/customers", headers=headers, params={"limit": 25})

if response.status_code == 200:
    customers = response.json()
    print(f"Opgehaalde klanten: {len(customers)}")
else:
    print(f"Fout {response.status_code}: {response.text}")

PHP (cURL)

<?php
$apiKey = getenv('SIDEFISH_API_KEY');
$url = 'https://sidefish.app/api/v1/customers?limit=25';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: ' . $apiKey,
    'Content-Type: application/json',
    'Accept: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Fout {$httpCode}: {$response}";
}
?>

---

5. Foutafhandeling & Statuscodes

Bij authenticatiefouten geeft de API een gestandaardiseerde JSON-foutmelding terug:

{
  "success": false,
  "error": "Invalid API Key: user not found.",
  "code": 10
}

HTTP Status	Oorzaak	Oplossing
401 Unauthorized	Ontbrekende of ongeldige API Key, of het gebruikersaccount bestaat niet meer.	Controleer de waarde van de header x-api-key.
403 Forbidden	Het gebruikersaccount is gedeactiveerd of heeft onvoldoende rechten voor dit endpoint.	Controleer of de gebruiker de status Actief heeft en over de juiste gebruikersgroep beschikt.
429 Too Many Requests	Te veel verzoeken binnen een korte tijdspanne (rate limiting).	Implementeer een exponential backoff in uw API-client.