Authentifizierung

Jede Anfrage an die CampOne-API muss mit einem mandantenbezogenen API key authentifiziert sein. Es gibt keinen benutzerbezogenen OAuth-Ablauf — Schlüssel gehören zum Mandanten, nicht zu einem einzelnen Betreiber.

Token-Format

Ein roher API key ist eine 32-Zeichen-Zeichenkette mit fester Form:

ck_<8-char visible prefix><24-char secret>

Ein vollständiges Beispiel (nicht verwenden — nur zur Veranschaulichung):

ck_a1b2c3d4XXXXXXXXXXXXXXXXXXXXXXXX

Die ersten 8 Zeichen (ck_a1b2c3 im Beispiel) bilden das sichtbare Präfix. Die Plattform speichert dieses Präfix im Klartext, sodass der Betreiber einen Schlüssel in der Admin-Konsole identifizieren kann, ohne den geheimen Teil zu sehen. Die übrigen 24 Zeichen sind das geheime Suffix, das im Ruhezustand gehasht abgelegt wird und nicht wiederherstellbar ist. Die vollständige 32-Zeichen-Zeichenkette wird mit jeder Anfrage gesendet.

Authorization-Header

Senden Sie das vollständige Token im Authorization-Header nach dem Bearer-Schema:

GET /api/v1/public/bookings/ HTTP/1.1
Host: api.campone.ch
Authorization: Bearer ck_a1b2c3d4XXXXXXXXXXXXXXXXXXXXXXXX
Accept: application/json

Ein vollständiges curl-Beispiel:

curl https://api.campone.ch/api/v1/public/bookings/ \
  -H "Authorization: Bearer ck_a1b2c3d4XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

Das Token bestimmt sowohl, gegen welchen Mandanten die Anfrage läuft, als auch was sie tun darf. Es gibt keinen separaten Mandanten-Header.

Wie ein Schlüssel ausgestellt wird

API keys werden in der Admin-Konsole von einem Mandanten-Administrator unter Einstellungen → API erzeugt. Der Administrator vergibt einen sprechenden Namen (z. B. „Booking.com sync”), wählt die benötigten Geltungsbereiche aus und legt optional ein Ablaufdatum fest. Die Plattform zeigt das rohe Token genau einmal zum Zeitpunkt der Erstellung an — kopieren Sie es sofort in Ihren Secrets-Manager. Geht es verloren, muss ein neuer Schlüssel erzeugt werden.

Falls die API für Ihren Mandanten noch nicht freigeschaltet ist, wenden Sie sich an Ihren Ansprechpartner bei CampOne, um einen Schlüssel ausstellen zu lassen.

Geltungsbereiche (Scopes)

Jeder Schlüssel trägt eine Liste von Scope-Strings. Der aufgerufene Endpunkt verlangt einen davon; fehlt der Geltungsbereich, antwortet die API mit 403. Verfügbare Geltungsbereiche:

Scope	Erlaubt
bookings:read	Buchungen auflisten und im Detail abrufen
bookings:write	Buchungen anlegen
sites:read	Stellplätze auflisten
customers:read	Kunden auflisten
invoices:read	Rechnungen auflisten

Ein Schlüssel kann eine beliebige Teilmenge davon halten. Fordern Sie das Minimum an, das Ihre Integration tatsächlich braucht — ein Channel-Manager, der nur neue Reservierungen einliefert, benötigt kein customers:read.

Schlüssel-Lebenszyklus

Erstellung. Ein Schlüssel ist sofort nach dem Erzeugen aktiv und wird ab der nächsten Anfrage akzeptiert.

Ablauf. Wurde bei der Erstellung ein Ablaufdatum gesetzt, funktioniert der Schlüssel ab diesem Zeitpunkt nicht mehr. Anfragen mit einem abgelaufenen Schlüssel liefern 401 key_inactive. Es gibt keine automatische Erneuerung — ein neuer Schlüssel muss vor Ablauf des alten erzeugt werden.

Deaktivierung / Widerruf. Ein Administrator kann einen Schlüssel über denselben Bildschirm Einstellungen → API widerrufen. Widerrufene Schlüssel liefern sofort 401 key_inactive. Es gibt keine Übergangsfrist — planen Sie Rotationen so, dass Ausfälle vermieden werden.

Rotation ohne Ausfall. So wird ein Schlüssel ohne Ausfallzeit rotiert:

1. Erzeugen Sie einen neuen Schlüssel mit denselben Geltungsbereichen.
2. Stellen Sie Ihre Integration auf das neue Token um (Deploy, Redeploy usw.).
3. Bestätigen Sie, dass der neue Schlüssel im Einsatz ist (die Admin-Konsole zeigt Zeitstempel der letzten Verwendung).
4. Widerrufen Sie den alten Schlüssel.

Die Plattform erkennt eine Kompromittierung nicht von selbst — bei Verdacht auf einen kompromittierten Schlüssel widerrufen Sie ihn manuell und prüfen Sie das Auditprotokoll auf ungewöhnliche Aktivität.

Authentifizierungsfehler (401)

Die API antwortet mit 401 Unauthorized und einem von zwei detail-Codes:

{ "detail": "invalid_key" }

Der Header fehlt, ist fehlerhaft, das Präfix existiert nicht, oder das Geheimnis stimmt nicht mit dem gespeicherten Hash überein.

{ "detail": "key_inactive" }

Der Schlüssel wurde gefunden, ist aber widerrufen oder abgelaufen.

In beiden Fällen sollte nicht erneut versucht werden — die Anfrage scheitert weiter, bis sich die Schlüsselsituation ändert.

Autorisierungsfehler (403)

Ist der Schlüssel gültig, trägt aber nicht den Geltungsbereich, den der Endpunkt verlangt, antwortet die API mit 403 Forbidden:

{ "detail": "You do not have permission to perform this action." }

Die Lösung liegt auf Betreiberseite: Bitten Sie die Person, die den Schlüssel verwaltet, den fehlenden Geltungsbereich zu ergänzen (oder einen neuen Schlüssel mit den richtigen Geltungsbereichen auszustellen). Erneute Versuche mit demselben Schlüssel helfen nicht.

Sicherheitshinweise

• Behandeln Sie das rohe Token wie ein Passwort. Wer es besitzt, kann die Daten des Mandanten innerhalb der gewährten Geltungsbereiche lesen oder verändern.
• Niemals ins Repository committen. Verwenden Sie einen Secrets-Manager, Umgebungsvariablen oder den Secret Store Ihrer Plattform.
• Niemals protokollieren. Entfernen Sie Authorization-Header aus den Request-Logs Ihrer eigenen Systeme.
• Die Plattform zeigt das rohe Token nach der Erstellung nicht erneut an. Wurde es nicht gespeichert, lässt es sich nicht wiederherstellen — erzeugen Sie in dem Fall einen neuen Schlüssel.
• Verwenden Sie für jede Anfrage TLS. Alle Endpunkte verlangen HTTPS; HTTP-Anfragen werden zurückgewiesen.