Authentifizierung

Überblick

Jeder Request braucht einen Authorization: Bearer <token>-Header. 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).

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.