Authentifizierung

Überblick

Jeder Request braucht einen Token. Im Normalfall reist er im Authorization: Bearer <token>-Header — die einzige Ausnahme ist der Query-Parameter für Tabellen-Importer weiter unten. Welcher Token es ist, hängt vom Szenario ab:

Szenario	Methode	Wo einrichten
Eigenes Skript, n8n, Zapier, Excel, Notebook	API-Key	Dashboard → API-Keys
SaaS / App, deren End-User sich mit bodenrichtwert.ai einloggen	OAuth 2.0 + PKCE (`authorization_code`)	Dashboard → OAuth-Apps
Server-Job oder CI, der im eigenen Namen läuft	Client Credentials (M2M)	Dashboard → OAuth-Apps

Alle drei Token-Typen laufen durch dieselbe serverseitige Validierung und werden als SHA-256-Hash gespeichert.

Weg 1: API-Key (einfachster Weg)

Persönlicher Access Token mit wählbarer Lebensdauer (30 Tage / 90 Tage / 1 Jahr / unbegrenzt). Die Nutzung zählt gegen deinen eigenen Account.

Login → Dashboard → API-Keys
„Neuer API-Key" anklicken, Namen vergeben (z.B. n8n-Produktion), Lebensdauer wählen.
Der Key wird genau einmal angezeigt — im Passwort-Manager oder Secret-Manager ablegen.
Sofort einsetzen:

curl -H "Authorization: Bearer brw_pat_…" \
  "https://api.bodenrichtwert.ai/api/bodenrichtwert?address=Hannover&nutzungsart=W"

Einen Key jederzeit im Dashboard widerrufen — die Wirkung tritt innerhalb von ~5 Minuten ein (Cloudflare-KV-Zwischenspeicher).

Query-Parameter für Tabellen-Importer

Manche Werkzeuge können technisch keine Header setzen. Google Sheets =IMPORTXML() und =IMPORTDATA() sind die häufigsten. Für sie — und nur für sie — akzeptiert die API denselben Token auch als Query-Parameter:

curl "https://api.bodenrichtwert.ai/api/bodenrichtwert?address=Hannover&nutzungsart=W&format=xml&token=brw_pat_…"

Der Authorization-Header hat Vorrang, wenn beides gesetzt ist. Der Parameter funktioniert an allen /api/*-Endpunkten; in Kombination mit format=xml entsteht daraus das Google-Sheets-Rezept.

Ein Schlüssel in der URL ist schwächer geschützt als einer im Header. Er steht in der Formel der Tabelle und ist damit für jeden sichtbar, der das Dokument öffnen darf — auch mit reinem Leserecht. Er landet außerdem leichter in Browser-Verlauf oder geteilten Links.Deshalb: nur nutzen, wenn das Werkzeug wirklich keine Header kann. Dafür einen eigenen Key mit Ablaufdatum anlegen, ihn nicht mit anderen Integrationen teilen und ihn bei Verdacht sofort widerrufen.Was wir auf unserer Seite tun: Antworten auf diesem Pfad gehen mit Cache-Control: no-store raus, und unsere Request-Logs sowie die Nutzungsstatistik erfassen ausschließlich den Pfad, nie den Query-String.

Überall sonst — eigene Skripte, Server, n8n, CI — bleibt der Authorization-Header der richtige Weg.

Weg 2: OAuth 2.0 mit PKCE (End-User-Flow)

Für Apps, bei denen Dritt-Nutzer sich mit ihrem bodenrichtwert.ai-Account einloggen — typisch für SaaS-Integrationen oder MCP-Clients wie Claude Desktop / ChatGPT. Nutzung zählt gegen den End-User.

1. App registrieren

Im Dashboard → OAuth-Apps eine neue App anlegen:

Name + Beschreibung (sichtbar im Consent-Dialog)
Typ: Public (Mobile / SPA) oder Confidential (Server)
Grant-Types: authorization_code
Redirect-URIs: mindestens eine HTTPS-URL (Localhost erlaubt)

Alternativ via RFC 7591 Dynamic Client Registration:

curl -X POST https://bodenrichtwert.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Mein Integration-Script",
    "redirect_uris": ["https://example.com/callback"]
  }'

2. Authorization Code holen

Leite den Nutzer zu /oauth/authorize um:

https://bodenrichtwert.ai/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://example.com/callback
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Nach Login und Consent erhältst du per Redirect einen code-Parameter.

3. Token einlösen

curl -X POST https://bodenrichtwert.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=CLIENT_ID" \
  -d "code_verifier=CODE_VERIFIER"

Antwort enthält access_token (1 h gültig) und refresh_token (30 Tage, rotierend).

Weg 3: Client Credentials (M2M)

Für Server-Jobs, die in deinem eigenen Namen laufen — Batch-Exporte, Cron-Jobs, interne Tools. Nutzung zählt gegen den App-Owner (dich).

1. Confidential App mit `client_credentials` anlegen

Im Dashboard → OAuth-Apps:

Typ: Confidential (Pflicht)
Grant-Types: client_credentials aktivieren
Redirect-URIs können leer bleiben

Nach dem Erstellen wird client_secret einmalig angezeigt — sicher ablegen.

2. Access Token holen

curl -X POST https://bodenrichtwert.ai/oauth/token \
  -u CLIENT_ID:CLIENT_SECRET \
  -d "grant_type=client_credentials"

Antwort:

{ "access_token": "…", "token_type": "bearer", "expires_in": 3600 }

Kein Refresh-Token — bei Bedarf einen neuen Access-Token holen (RFC 6749 §4.4.3).

3. Token verwenden

curl -H "Authorization: Bearer …" \
  "https://api.bodenrichtwert.ai/api/bodenrichtwert?address=Köln"

Secret rotieren, sobald du einen Verdacht auf Kompromittierung hast — im Dashboard → OAuth-Apps per „Secret rotieren"-Button. Das alte Secret wird sofort ungültig.