Authentifizierung
Jede authentifizierte Anfrage trägt einen Bearer-API-Schlüssel. Der Schlüssel bestimmt, für welche Unterkunft Sie handeln und welche Scopes Sie nutzen dürfen. Es gibt keine Benutzernamen, Passwörter oder OAuth-Abläufe: ein Schlüssel pro Integration.
Ein Veridien-API-Schlüssel sieht so aus:
vrdn_live_xxxxxxxxxxxxxxxxxxxx- Er trägt das Präfix
vrdn_live_. - Er wird einmal angezeigt, bei der Erstellung. Veridien speichert nur einen SHA-256-Hash des Schlüssels, er lässt sich nie wieder abrufen, nur widerrufen und ersetzen.
- Er ist an eine Unterkunft gebunden. Die Unterkunft ergibt sich aus dem Schlüssel, deshalb verlangt kein Endpunkt eine Unterkunfts-ID von Ihnen.
Behandeln Sie Schlüssel wie Passwörter
Ein Schlüssel gewährt seine Scopes auf den echten Daten Ihrer Unterkunft. Bewahren Sie ihn serverseitig in einem Secret-Store oder einer Umgebungsvariablen auf, nie in Client-Code oder einem öffentlichen Repository. Wenn ein Schlüssel nach außen gelangt, widerrufen Sie ihn sofort und geben Sie einen neuen aus.
Schlüssel legen Sie im Dashboard unter Einstellungen → API-Schlüssel an:
- Klicken Sie auf Schlüssel erstellen und geben Sie ihm einen sprechenden Namen (zum Beispiel
Sunrise Bay booking engine). - Wählen Sie die Scopes, die die Integration braucht, und vergeben Sie das Minimum.
- Kopieren Sie den Schlüssel aus dem Bestätigungsdialog und bewahren Sie ihn sicher auf. Er wird kein zweites Mal angezeigt.
Schlüssel lassen sich auf demselben Bildschirm jederzeit widerrufen. Ein widerrufener Schlüssel funktioniert sofort nicht mehr, Anfragen damit liefern dann 401.
Setzen Sie den Schlüssel bei jeder Anfrage in den Authorization-Header:
curl https://veridien.app/api/v1/me \
-H "Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx"Ein erfolgreicher Aufruf von /me bestätigt, dass der Schlüssel funktioniert, und nennt seine Unterkunft und seine Scopes:
{
"property_id": "p_8f2a1c",
"property_slug": "sunrise-bay",
"scopes": ["availability:read", "reservations:write", "folio:write"],
"request_id": "req_a1b2c3d4e5"
}Fehlt der Header oder ist er fehlerhaft, erhalten Sie 401 missing_api_key. Ist der Schlüssel unbekannt, deaktiviert oder abgelaufen, erhalten Sie 401 invalid_api_key.
Ein Schlüssel darf einen Endpunkt nur aufrufen, wenn er dessen Scope besitzt. Ein Aufruf ohne den passenden Scope liefert 403 insufficient_scope. Scopes folgen dem Muster resource:action.
| Scope | Erlaubt |
|---|---|
availability:read | Verfügbarkeit und Raten lesen (/availability, /rates, /room-types, /services und veröffentlichte Angebote). |
rates:read | Ressourcen der Ratenverwaltung lesen (GET /rate-plans/{id}/intervals, /inclusions, /promo-codes). Die Leseendpunkte für Preise (/rates, /rate-plans) akzeptieren availability:read. |
rates:write | Ratenpläne und Promotions, Saisonintervalle, Inklusivleistungen und Guthaben sowie Promo-Codes anlegen, ändern und löschen (/rate-plans, /intervals, /promo-codes). |
reservations:read | Reservierungen auflisten und lesen (/reservations, /reservations/{id}). |
reservations:write | Holds anlegen, Reservierungen bestätigen und stornieren (/holds, /holds/{id}/confirm, /reservations/{id}/cancel). |
guests:read | Gästeprofile ohne personenbezogene Daten lesen. |
guests:read:pii | Zusätzlich die personenbezogenen Gastdaten liefern (E-Mail, Telefon, Adresse, Ausweisdokument). |
guests:write | Gäste registrieren, verknüpfen und aktualisieren (POST /guests, PATCH /guests/{id}). |
loyalty:read | Punktestand, Stufe und Journal des Treuekontos eines Gastes lesen. |
loyalty:write | Treuepunkte einlösen (/loyalty/redemptions). |
folio:read | Das Gastkonto einer Reservierung lesen. |
folio:write | Gebühren auf ein Gastkonto buchen (/reservations/{id}/folio/charges). |
webhooks:manage | Reserviert für die kommende Verwaltung von Webhook-Abonnements. |
So wenig Rechte wie möglich
Vergeben Sie nur die Scopes, die eine Integration braucht. Ein reines Lese-Widget für Verfügbarkeit braucht nur availability:read, eine vollständige Buchungsmaschine üblicherweise availability:read, guests:write, reservations:write und folio:write, dazu loyalty:*, wenn sie Punkte anzeigt.
Gästeprofile teilen sich in eine Basisansicht und eine Ansicht mit personenbezogenen Daten. Mit guests:read erhalten Sie Kennungen und unkritische Felder (Name, Nationalität, Status, Kennzeichen der Einheimischen-Verifizierung). Um zusätzlich email, phone, address und die Ausweisfelder zu erhalten, muss der Schlüssel auch guests:read:pii tragen. So können Sie etwa ein öffentliches Widget bauen, das den Gaststatus liest, ohne je Kontaktdaten preiszugeben.
Zwei Meta-Endpunkte brauchen weder Schlüssel noch Scope:
GET /health: eine Lebendprüfung, die{ "status": "ok" }zurückgibt.GET /openapi.json: das OpenAPI-3.1-Schema der gesamten API.
Alles andere verlangt einen gültigen Schlüssel mit dem passenden Scope.
- Konventionen: Fehler, Idempotenz, Paginierung und Rate Limits.
- Schnellstart: ein vollständiger Buchungsablauf vom Schlüssel bis zur bestätigten Reservierung.