Authentifizierung

Zwei Wege zur Authentifizierung

Jede Anfrage an /api/v1/ muss authentifiziert sein. PIE akzeptiert zwei Arten von Anmeldedaten, und beide werden serverseitig zu demselben organisationsbezogenen Principal aufgelöst:

• API-Schlüssel — langlebige Maschine-zu-Maschine-Anmeldedaten, die im Header X-API-Key gesendet werden. Ideal für Server-Integrationen.
• JWT-Bearer-Token — kurzlebige Token, die bei einer Anmeldung ausgestellt und im Header Authorization gesendet werden. Ideal für interaktive Sitzungen.

API-Schlüssel

Erstellen Sie einen Schlüssel auf der Seite API-Schlüssel in Ihrem Producer- (PIP) oder Buyer-Portal (PIC). Das Geheimnis wird bei der Erstellung einmalig angezeigt — speichern Sie es sicher; PIE bewahrt nur einen SHA-256-Hash auf und kann es nie wieder anzeigen. Senden Sie es bei jeder Anfrage:

curl https://api.example.com/api/v1/products \
  -H "X-API-Key: pie_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Schlüssel tragen Scopes (zum Beispiel products:read, products:write), die groben Lese-/Schreibzugriff gewähren, und können als Sandbox markiert werden (nur lesend — siehe unten). Rotieren Sie einen Schlüssel, um einen Ersatz zu erzeugen, während der alte während eines kurzen Gnadenzeitraums weiter funktioniert; widerrufen Sie ihn dann, um ihn sofort ungültig zu machen.

Sandbox-Schlüssel

Ein Sandbox-Schlüssel liest die echten Daten Ihrer Organisation, weist aber jede verändernde Anfrage mit 403 SANDBOX_READONLY ab. Jede Antwort auf einen Sandbox-Schlüssel trägt den Header X-PIE-Sandbox: true. Verwenden Sie einen solchen Schlüssel, um die API zu erkunden — einschließlich des Try it-Runners in der API-Referenz — ohne Risiko, Produktivdaten zu verändern.

JWT-Bearer-Token

Tauschen Sie Anmeldedaten unter POST /api/v1/auth/login gegen ein kurzlebiges Access-Token, und senden Sie es dann als Bearer-Token:

curl https://api.example.com/api/v1/products \
  -H "Authorization: Bearer eyJhbGciOi..."

Access-Token laufen schnell ab; verwenden Sie POST /api/v1/auth/refresh, um über das Refresh-Cookie ein neues zu erhalten. Anders als API-Schlüssel werden Bearer-Principals nicht über Scopes eingeschränkt — ihr Zugriff richtet sich vollständig nach der Rolle des angemeldeten Benutzers.