Authentifizierung

Jeder Request an https://wohno.de/api/v1/* wird über einen API-Key im X-API-Key-Header authentifiziert. Es gibt zwei Key-Typen — die Wahl des richtigen ist die wichtigste Authentifizierungs-Entscheidung, die du triffst.

Publishable- vs. Secret-Keys#

sk_test_* / pk_test_* existieren für Sandbox-Setups.

Wann welcher#

• Secret (sk_) — überall dort, wo der Key geheim bleiben kann: Backends, Cron-Jobs, CRM-Sync, Server-zu-Server-Integrationen. Er darf lesen, schreiben und löschen. Ein Secret Key wird nur als bcrypt-Hash gespeichert und genau einmal im Klartext zurückgegeben — kopiere ihn beim Erstellen.
• Publishable (pk_) — überall dort, wo der Key im Browser landet: Embed-Widgets, öffentliches HTML, clientseitiges JS. Er darf nur die Read-only-Whitelist tragen und muss eine Origin-Allowlist haben. Publishable Keys sind bewusst browser-sicher: Ihre Sicherheit kommt aus der Scope-Whitelist plus der Origin-Allowlist, nicht aus der Geheimhaltung.

Faustregel: Wenn ein Wert jemals einen Browser erreicht, muss es ein pk_-Key sein. Packe niemals einen Secret Key in ein Frontend-Bundle.

Scopes#

Scopes folgen dem Format resource:action (z. B. listings:read) und sind hierarchisch:

• * gewährt Vollzugriff.
• resource:* gewährt alle Aktionen auf dieser Ressource.
• delete impliziert write, und write impliziert read.

Ein fehlender Scope liefert 403 INSUFFICIENT_SCOPE. Die vollständige Scope-Registry findest du in der Konventions-Referenz.

Publishable-Whitelist#

Ein pk_-Key darf nur diese Read-Scopes tragen:

• organizations:read
• listings:read
• embed:read
• appointments:read
• appointments:book

Das wird zweifach durchgesetzt (Defense-in-Depth): in der Applikationsschicht und durch einen Datenbank-Trigger.

Origin- und IP-Allowlists#

• Die Origin-Allowlist ist für pk_-Keys Pflicht und für sk_-Keys optional.
  • Subdomain-Wildcards wie https://*.example.com matchen genau eine Subdomain-Ebene.
  • HTTPS ist Pflicht (außer http://localhost).
  • Browser senden den Origin-Header automatisch. Fehlt er bei einem pk_-Call, ist der Request fehlerhaft und liefert 403 ORIGIN_REQUIRED.
  • Ein Origin, der zu keinem Allowlist-Eintrag passt, liefert 403 ORIGIN_NOT_ALLOWED.
• Die IP-Allowlist ist nur für sk_-Keys sinnvoll (IPv4 + IPv4-CIDR, max. 10 Einträge). Empfohlen für produktive Server-zu-Server-Keys. Ein Request von einer IP außerhalb der Liste liefert 403 IP_NOT_ALLOWED.

Key-Rotation#

Rotiere einen Key ohne Downtime über eine Overlap-Periode:

1. Ein neuer Key wird mit dem gleichen Profil erstellt (Typ, Scopes, Allowlists); sein Roh-Wert wird einmal zurückgegeben.
2. Der alte Key erhält ein rotation_expires_at = now() + overlapDays (Standard 7 Tage, 1–30 erlaubt).
3. Beide Keys validieren während des Overlap-Fensters — rolle den neuen Key aus und mottet dann den alten ein.
4. Nach dem Fenster liefert der alte Key 401 KEY_ROTATED_OUT und wird von einem nächtlichen Cleanup-Job widerrufen.

Empfehlung: alle 90 Tage rotieren; ein 7-Tage-Overlap reicht für ein Deployment.

Rate-Limit- und Quota-Header#

Jede /api/v1/*-Antwort trägt informative Header, mit denen du dich selbst drosseln kannst.

Rate-Limits (pro Key, 1000 req/h)#

Überschreiten des Limits liefert 429 RATE_LIMITED. Nutze exponentielles Backoff und respektiere Retry-After.

Quotas (pro Organisation, monatlich)#

soft-warning wird ab ≥ 80 % Nutzung gesetzt. Quotas sind standardmäßig nur Tracking; sobald sie durchgesetzt werden, liefert eine Überschreitung 429 QUOTA_EXCEEDED.

Authentifizierungs-Fehler#

Verzweige über den stabilen error.code-String, niemals über die menschenlesbare message.

Referenz#

Die kanonischen, code-verifizierten Details zu Authentifizierung, Scopes, Fehlerformaten und Headern findest du in der API-Konventions-Referenz.