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; die meisten Schreibrouten akzeptieren zusätzlich einen Idempotency-Key für sichere Retries. Verfügbar in jedem Plan einschließlich Free. Tageskontingente gelten nur für Free (100 Schreibvorgänge + 100 Pass-Abrufe pro API-Schlüssel) und Basic (200 + 200); 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.
| Scope | Gewährt |
|---|---|
| passports:read | Produkte und digitale Produktpässe ansehen |
| passports:write | Pässe erstellen und aktualisieren (die Veröffentlichung bleibt im Dashboard) |
| regulatory:read | DPP-Scope-Anwendbarkeit prüfen (Scope-Check- und DPP-Assistenten-Tools) |
| documents:read | Reserviert — noch keine v1-Endpoints |
| documents:write | Reserviert — noch keine v1-Endpoints |
| suppliers:read | Reserviert — noch keine v1-Endpoints |
| suppliers:write | Reserviert — noch keine v1-Endpoints |
| offline_access | Refresh Token ausstellen (verbunden bleiben) |
Idempotency-Key
Ausgewählte v1-Schreibrouten akzeptieren einen Idempotency-Key-Header — Produkte (erstellen, Batch, aktualisieren, löschen, archivieren), Pässe (erstellen, Batch, aktualisieren, archivieren, suspendieren, Feld-Update, Parteien-Update, Zustandsflags, Messwert-Erfassung), EPCIS-Capture und Scope-Katalog-Läufe. Senden Sie eine UUID v4 (oder einen beliebigen opaken String ≤ 64 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 liefert 422 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 gelten zwei Obergrenzen, gezählt pro API-Schlüssel (eine OAuth-App hat ihren eigenen Zähler):
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 gelesene Pässe: Ein Listenaufruf zählt seine Seitengröße (limit, Standard 20), auch wenn die letzte Seite weniger liefert; jeder andere Lesezugriff zählt 1 (ein einzelner Pass, sein QR-Code, Snapshots, EPCIS-Dokument, Konformitätsprüfung und Registerbereitschaft sowie EPCIS-Abfrage, ein EPCIS-Erfassungsauftrag und der Scope-Katalog). Vom Schreib-Budget getrennt, damit ein ERP, das Updates pusht, Ihre Lesequote nicht aushungert und umgekehrt.
| Plan | Schreibvorgänge / Tag | Pass-Lesevorgänge / Tag |
|---|---|---|
| Free | 100 | 100 |
| Basic | 200 | 200 |
| Starter | Unbegrenzt | Unbegrenzt |
| Growth | Unbegrenzt | Unbegrenzt |
| Scale | Unbegrenzt | Unbegrenzt |
| Pro | Unbegrenzt | Unbegrenzt |
| Enterprise | Unbegrenzt | Unbegrenzt |
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 Limit — maxDpps — begrenzt die Zahl veröffentlichter Pässe in Ihrem Workspace. Ein über die API angelegter Pass ist ein Entwurf und belegt keinen Platz, daher liefert das Anlegen nie einen Overage-Fehler. Das Limit greift beim Veröffentlichen im Dashboard. Über dem Limit fragt das Dashboard, ob Sie die Pro-Pass-Overage-Gebühr bestätigen, oder lehnt ab, wenn Ihr Plan keinen Overage-Preis hat; dann upgraden Sie oder archivieren Pässe. Siehe den Endpoint Create a passport.
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.