Schlüssel und Authentifizierung

Öffentlicher und geheimer Schlüssel

Der öffentliche Schlüssel wird in der URL als ?key= übertragen. Er ist bewusst öffentlich: Er steht im Quelltext Ihrer Seite und funktioniert nur von den Origins aus, die für ihn eingetragen sind. Der geheime Schlüssel wird als Authorization: Bearer <key> übertragen und ist nur für Ihren Server bestimmt. Ein Browser kann ihn gar nicht an den Dienst senden: Authorization steht nicht in der CORS-Allowlist.

Erlaubte Origins

Jeder öffentliche Schlüssel trägt eine Liste mit bis zu 20 Origins: Schema, Host und Port genau so, wie der Browser sie sendet, etwa https://shop.example.com. Eine Anfrage von jeder anderen Origin wird mit 403 origin_not_allowed abgewiesen, der Preflight eingeschlossen, und der Dienst antwortet nie mit Access-Control-Allow-Origin: *. Die Liste ist ein Signal, keine Authentifizierung: Die eigentlichen Schutzmaßnahmen sind der serverseitige Preis und die Ratenlimits.

Testschlüssel

Ein Live-Shop kann bis zu 3 Testschlüssel anlegen (pk_test_…, sk_test_…). Ein Testschlüssel rechnet mit Ihrem neuesten validierten Entwurf, sodass Sie eine Änderung ausprobieren können, bevor Sie sie veröffentlichen. Er wird nicht abgerechnet, seine Bestellungen lösen weder Webhook noch E-Mail aus, und er läuft nach 30 Tagen ab. Test und Live vermischen sich nie: Ein Test-Angebot wird nur mit einem geheimen Testschlüssel geprüft, eine Testbestellung ist nur für einen Testschlüssel sichtbar, und ein Live-Schlüssel sieht sie nie. Ein Testschlüssel darf http://localhost als Origin eintragen.

Das Projekt-Token

Gespeicherte Projekte gehören zu einem Kunden, nicht zu einem Login. Der erste POST /cfg/v1/projects stellt ein zufälliges Token (cfgpt_…) aus und gibt es nur einmal zurück; das Embed behält es und sendet es bei jedem weiteren Projektaufruf als X-Cfg-Project-Token. Das Token eines anderen Kunden, der Schlüssel eines anderen Shops und eine unbekannte ID erhalten alle dieselbe Antwort 404.

Rotation ohne Ausfall

Die Rotation erfolgt in der Konsole, und jede Schlüsselart hat eine Überlappung, damit beim Wechsel nichts bricht.

• Öffentlicher Schlüssel: Der neue Schlüssel übernimmt dieselbe Origin-Liste; der alte funktioniert standardmäßig noch 168 Stunden (höchstens 720).
• Geheimer Schlüssel: wird nur einmal angezeigt; der alte Schlüssel authentifiziert standardmäßig noch 24 Stunden (höchstens 720).
• Angebots-Signaturschlüssel: Der neue Schlüssel signiert ab sofort; vom alten Schlüssel signierte Angebote werden weiterhin geprüft und können noch bis zu 31 Tage bestellt werden.
• Webhook-Secret: Während eines Wechsels signieren beide Secrets jede Zustellung 7 Tage lang, als zwei v1=-Werte, sodass Ihr Empfänger beide verarbeiten kann.

Was nie in einen Browser gehört

Der geheime Schlüssel und das Webhook-Secret (whsec_…). Bewahren Sie sie in der Umgebung Ihres Servers auf, nie in einer Seite, einem Repository oder einem Log. Wenn einer davon offengelegt wird, rotieren Sie ihn in der Konsole.