--- title: Authentifizierung description: Zwei Auth-Methoden — API-Schlüssel (Bearer) und OAuth 2.0 mit PKCE — plus Idempotency-Key für sichere Retries und planabhängige Rate-Limits für v1. canonical: "https://www.tracepass.eu/de/docs/authentication" locale: de source: "https://www.tracepass.eu/de/docs/authentication" --- # Authentifizierung > Zwei Auth-Methoden — API-Schlüssel (Bearer) und OAuth 2.0 mit PKCE — plus Idempotency-Key für sichere Retries und planabhängige Rate-Limits für v1. 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-Key`fü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: ```bash curl -sS https://app.tracepass.eu/api/v1/products \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" ``` **Tip —** Ein geleakter Schlüssel ist mit einem Klick widerrufbar — öffnen Sie Developer → API keys, klicken Sie auf **Revoke**, und der Schlüssel liefert innerhalb von Sekunden 401\. Audit-Log-Einträge zum Schlüssel bleiben erhalten, sodass Sie nachvollziehen können, was unter ihm geschrieben wurde. ## 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, aktualisieren und veröffentlichen | | documents:read | Hochgeladene Dokumente und Extraktionen lesen | | documents:write | Dokumente hochladen und KI-Extraktionen starten | | suppliers:read | Lieferantenanfragen ansehen | | suppliers:write | Lieferantenanfragen erstellen und verwalten | | offline\_access | Refresh Token ausstellen (verbunden bleiben) | **Tip —** Nutzer sehen und trennen die von ihnen autorisierten Apps unter **Developer → OAuth Apps → Connected Apps**; das Trennen widerruft die Tokens der App sofort. Ihre eigenen registrierten Apps können Sie auf demselben Bildschirm löschen. ## 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. ```bash 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 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. | 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 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](/de/docs/create-passport) für den Overage-Flow. **Mehr Spielraum nötig?** Upgraden Sie Ihren Plan im Dashboard (sofort wirksam) oder kontaktieren Sie [support@tracepass.eu](mailto:support@tracepass.eu) für ein Enterprise-Angebot. Wir berechnen keine Pro-Scan-Gebühr im öffentlichen Pass-Viewer — gezählt werden nur Schreibvor­ gänge über diese API. ## 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.