Authentifizierung

TracePass v1 unterstützt zwei Auth-Methoden. Ein API-Schlüssel (ein statischer Bearer Token) ist am einfachsten — ideal für Server-zu-Server- und ERP- Integrationen. OAuth 2.0 mit PKCE ist für Drittanbieter-Apps und KI-Assistenten, die im Namen eines Nutzers mit scoped, widerrufbarem Zugriff handeln. Beide werden als Bearer Token im Standard- Authorization-Header übergeben; jeder Schreibvorgang akzeptiert zusätzlich einen Idempotency-Keyfür sichere Retries. Verfügbar in jedem Plan einschließlich Free. Tägliches Aufrufkontingent gilt nur für Free (100/Tag) und Basic (200/Tag); Starter und höher sind unbegrenzt.

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"

OAuth 2.0 (nutzerautorisierte Apps)

Wenn Sie eine App bauen, die andere TracePass-Nutzer verbinden — oder einen KI-Assistenten, den ein Nutzer autorisiert —, verwenden Sie OAuth 2.0, statt sie um das Einfügen eines API-Schlüssels zu bitten. Der Nutzer genehmigt bestimmte Scopes auf einem Zustimmungsbildschirm; der erzeugte Access Token ist auf die Schnittmenge aus seiner Dashboard-Rolle und den gewährten Scopes beschränkt. Registrieren Sie Ihre App unter Developer → OAuth Apps (oder programmatisch via Dynamic Client Registration unter /api/oauth/register). Wir unterstützen den Authorization-Code-Flow mit PKCE — öffentliche Clients (SPA / Mobile / MCP) brauchen kein Secret; vertrauliche serverseitige Clients erhalten eines.

Der Ablauf

Discovery-Metadaten liegen unter /.well-known/oauth-authorization-server (RFC 8414). Kurz gefasst: (1) leiten Sie den Nutzer zu /api/oauth/authorize mit Ihrer client_id, redirect_uri, dem angeforderten scope, state und einem PKCE-code_challenge (S256); (2) er stimmt zu, und wir leiten mit einem einmaligen code zurück; (3) tauschen Sie diesen unter /api/oauth/token mit Ihrem code_verifier gegen einen 15-minütigen Access Token (plus Refresh Token, wenn offline_access gewährt wurde). Refresh Tokens rotieren bei jeder Nutzung; widerrufen Sie unter /api/oauth/revoke (RFC 7009).

Scopes

Fordern Sie nur an, was Ihre App braucht — der Zustimmungsbildschirm zeigt dem Nutzer genau diese. Ein Schreib-Scope erfordert zusätzlich, dass der autorisierende Nutzer eine schreibberechtigte Dashboard-Rolle hat, sodass ein Viewer, der passports:write gewährt, trotzdem nicht schreiben kann. API-Schlüssel hingegen sind „alles oder nichts“ und ignorieren Scopes.

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: 200 writes/day via /api/v1. Currently 200 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

Der OAuth-Client-Credentials-Grant (Maschinenidentität ohne Nutzer) und IP-Allow-Listing stehen auf der Roadmap, sind aber noch nicht ausgeliefert. Für reinen Server-zu-Server-Zugriff verwenden Sie heute einen API-Schlüssel — erzeugen Sie einen pro Integration, um auf Integrationsebene widerrufen zu können.