Schlüsselarten und Bindung

Jeder Aufruf (außer /v1/health) braucht einen API-Key im Header Authorization: Bearer …. Es gibt zwei Arten:

	Geheimer Key `pz_sk_…`	Öffentlicher Key `pz_pk_…`
Einsatz	von Ihrem Server (Backend, CMS, Skript)	direkt aus dem Browser (Website ohne Backend)
Endpunkte	alle	Adressvorschläge und Reisezeiten (kein Geocoding, keine Isochronen)
Bindung	optional an Server-IPs bzw. Netze (CIDR)	Pflicht: erlaubte Domains (`Origin`)
Standard-Limits	600 Anfragen/Min., 200.000/Tag; Isochronen zusätzlich 60/Min., 10.000/Tag	600/Min. und 50.000/Tag je Key, zusätzlich 120/Min. und 2.000/Tag je Besucher-IP

Die Limits sind Standardwerte und können je Key und je Mandant angepasst werden.

Geheimer Key

Gehört nur auf den Server, nie in JavaScript, Apps oder öffentliche Repositories.
Die API lehnt einen geheimen Key ab, wenn die Anfrage einen Origin-Header hat – so fällt ein versehentlicher Einsatz im Browser sofort auf (403).
Mit IP-Bindung gilt der Key nur von den freigegebenen Server-IPs aus. Das empfiehlt sich, wenn Ihre Server feste Adressen haben.
Nur der geheime Key darf POST /v1/address/geocode nutzen (Adresslisten in Koordinaten umwandeln, z. B. für Ihre Standorte) und POST /v1/isochrones (Erreichbare Flächen auf Karten).

Öffentlicher Key

Ist im Quelltext Ihrer Seite sichtbar – das ist so vorgesehen. Geschützt wird er durch die Domainbindung: Die API prüft den Origin-Header, den der Browser selbst setzt, und beantwortet nur freigegebene Domains (inkl. CORS-Header).
Domains werden genau angegeben, mit Schema und ggf. Port: https://www.example.org, https://karriere.example.org. Für Test- und Vorschauumgebungen eigene Einträge anlegen.
Weil sich der Origin-Header außerhalb des Browsers fälschen lässt, gelten zusätzlich enge Limits je Besucher-IP. Bei Missbrauch wird der Key gesperrt und erneuert.

Keys erhalten, sperren, erneuern

Keys vergibt der Betreiber des Dienstes. Der Key wird nur einmal im Klartext angezeigt und danach nur noch als Hash gespeichert – bewahren Sie ihn sicher auf (z. B. als Umgebungsvariable). Bei Verdacht auf Missbrauch: Key sperren lassen; die Sperre wirkt sofort. Beim Erneuern entsteht ein neuer Key mit denselben Einstellungen, der alte ist sofort ungültig.

Typische Antworten

Status	Bedeutung
`401`	Key fehlt, ist unbekannt oder gesperrt
`403`	Key gültig, aber nicht erlaubt: falsche Domain bzw. Server-IP, Endpunkt für diese Schlüsselart gesperrt, geheimer Key im Browser
`429`	Limit erreicht; der Header `Retry-After` nennt die Wartezeit in Sekunden

Ob ein Key funktioniert, prüfen Sie am einfachsten mit einem Adressvorschlag:

Shell

curl -sS -o /dev/null -w '%{http_code}\n' 'https://api.pendelzeit.de/v1/address/suggest?q=Ulm' \
  -H 'Authorization: Bearer pz_sk_IHR_GEHEIMER_KEY'

Erwartet: 200. Den öffentlichen Key prüfen Sie im Browser auf einer freigegebenen Domain oder mit gesetztem Origin:

Shell

curl -sS -o /dev/null -w '%{http_code}\n' 'https://api.pendelzeit.de/v1/address/suggest?q=Ulm' \
  -H 'Authorization: Bearer pz_pk_IHR_OEFFENTLICHER_KEY' \
  -H 'Origin: https://www.example.org'