Authentifizierung

TracePass v1 nutzt einen einzigen Auth-Mechanismus: einen statischen API-Schlüssel, übergeben als Bearer Token im Standard-Authorization-Header. Jeder Schreibvorgang akzeptiert zusätzlich einenIdempotency-Keyfür sichere Retries. Limits gelten pro Plan, pro UTC-Tag — verfügbar in jedem Plan einschließlich Free, mit täglichem Aufrufkontingent, das mit dem Plan skaliert.

API-Schlüssel

Erzeugen Sie Schlüssel unter Developer → API keys im Dashboard. Schlüssel sind workspace-gebunden: Jeder Schlüssel gehört zu einem Workspace und übernimmt dessen Plan, Limits und Audit-Log. Schlüssel tragen das Präfix tp_, gefolgt von einem opaken Zufallssuffix — es gibt kein separates live- / test-Präfix und keine env-namensraumbezogene Sandbox. Testen Sie in Ihrem Free- oder Basic-Workspace, falls Sie eine Nicht-Produktions-Umgebung brauchen.

Übergeben Sie den Schlüssel als Bearer Token bei jeder Anfrage:

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

Idempotency-Key

Jeder POST, PATCH und DELETE auf der v1-Schnittstelle akzeptiert einen Idempotency-Key-Header. Senden Sie eine UUID v4 (oder einen beliebigen opaken String ≤ 255 Zeichen) pro logischer Operation; die Plattform speichert die erste Antwort 24 Stunden lang und spielt sie zurück, wenn derselbe Schlüssel + derselbe Workspace erneut auftauchen. Netzwerk-Retries werden sicher — Sie erstellen keinen Pass doppelt, nur weil Ihr HTTP-Client bei einem transienten 5xx erneut versucht hat.

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "...", "gs1": { "gtin": "...", "serialNumber": "..." } }'

Wiederverwendung desselben Schlüssels mit einem anderen Request-Body liefert422 Unprocessable Entity mit error: "Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body." — die Plattform überschreibt nicht stillschweigend, weil das fast immer ein Client-Bug ist. Erzeugen Sie für tatsächlich neue Operationen einen frischen Schlüssel.

Rate-Limits

Pro UTC-Tag und Workspace gelten zwei Obergrenzen:

1. v1-Schreib-Budget — `maxV1WritesPerDay`

Zählt jeden POST / PATCH / DELETE auf der v1-Schnittstelle. Lesevorgänge fallen nicht unter diesen Zähler.

2. v1-Pass-Lese-Budget — `maxV1PassportsPerDay`

Zählt jeden GET auf den Pass-Endpoints (Einzellesen + paginierte Liste). Vom Schreib-Budget getrennt, damit ein ERP, das Updates pusht, Ihre Lesequote nicht aushungert und umgekehrt.

Wenn Sie eine der beiden Obergrenzen erreichen, lautet die Antwort 429 Too Many Requests mit einem Body wie { "error": "API rate limit: 500 writes/day via /api/v1. Currently 500 today; requested 1. Retry tomorrow (UTC) or upgrade your plan." }. Das Fenster setzt um 00:00 UTC zurück; wir unterstützen keine rollierenden Fenster, da sie das Limit nachgelagert schwerer nachvollziehbar machen.

Ein separates Kontingent — maxDpps — begrenzt die Gesamtzahl aktiver DPPs in Ihrem Workspace und wird über eine 402-Antwort mit einem overage_required-Body durchgesetzt, wenn der Plan Pro-Pass-Overage unterstützt. Siehe den Endpoint Create a passport für den Overage-Flow.

Was wir (noch) nicht unterstützen

OAuth-2.0-Client-Credentials, scoped Sub-Keys und IP- Allow-Listing stehen auf der Roadmap, sind aber noch nicht ausgeliefert. Wenn Sie heute eines davon brauchen, erzeugen Sie einen neuen API-Schlüssel pro Integration, um auf Integrationsebene widerrufen zu können — das ist der Workaround.