Authentifizierung

Jeder Aufruf der Rekomi-API braucht einen Bearer-Schlüssel. Manche Aufrufe (S2S-Tracking, Zustellung von Webhooks) brauchen zusätzlich eine HMAC-Signatur mit einem separaten Signatur-Secret. Diese Seite behandelt beides.

Einen API-Schlüssel erzeugen

Erstelle deinen Schlüssel im Dashboard: Öffne /dashboard/settings/api-keys und klicke auf „Schlüssel erstellen“.

Nur der Owner des Workspace kann API-Schlüssel erstellen, rotieren oder widerrufen. Zum Erstellen und Rotieren brauchst du mindestens den Plan Starter; widerrufen kannst du in jedem Plan (damit auch eine Marke nach einem Downgrade noch aufräumen kann).

Pflichtangaben:

• Name: eine gut lesbare Bezeichnung wie „Vercel production“ oder „data warehouse sync“.
• Berechtigungen (Scope): Wähle Read (nur GET-Anfragen) und/oder Write (Erstellen, Aktualisieren, Löschen).

Klicke auf Erstellen. In einem Dialog erscheinen zwei Werte, GENAU EINMAL:

• Bearer-Schlüssel im Klartext: beginnt mit rk_live_. 32 zufällige Bytes, base64url-kodiert. Kopiere ihn sofort.
• Signatur-Secret im Klartext: beginnt mit rks_. 32 zufällige Bytes. Wird für die HMAC-Signatur an den S2S-Endpunkten verwendet. Kopiere es sofort.

Sobald du den Dialog schließt, lassen sich die Klartextwerte nicht mehr wiederherstellen. Den Bearer-Schlüssel speichern wir nur als SHA-256-Hash. Das Signatur-Secret wird verschlüsselt gespeichert.

Wenn du deine Schlüssel verlierst, rotiere sie (siehe unten) oder widerrufe sie und erstelle neue.

Der gesamte Lebenszyklus eines Schlüssels (Erstellen, Rotieren, Widerrufen) braucht eine interaktive Dashboard-Sitzung: Ein bestehender API-Schlüssel oder ein OAuth-Token kann nie Schlüssel erzeugen, rotieren oder widerrufen (403 interactive_session_required). Dasselbe gilt für MCP-Verbindungstokens. Ein geleakter Schlüssel kann sich also nie neue Zugangsdaten verschaffen.

Den Bearer-Schlüssel verwenden

Setze bei jeder Anfrage den Header Authorization:

GET /api/v1/programs
Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx

Der Bearer-Schlüssel identifiziert deine Organisation. Einen separaten Header X-Org-ID brauchen wir nicht; der Bearer-Schlüssel enthält alles, was wir brauchen.

Berechtigungen

Das Feld scopes eines Schlüssels ist ein Array mit "read" und/oder "write":

• read: nur GET-Endpunkte. Kann keine Ressourcen erstellen, aktualisieren oder löschen. Kann keine Schlüssel rotieren.
• write: Zugriff zum Erstellen, Aktualisieren und Löschen über POST, PATCH, DELETE. Es gelten die Rollenprüfungen der einzelnen Endpunkte (manche Endpunkte verlangen zusätzlich die Rolle Owner oder Admin). Ein Schlüssel ohne write kann nichts verändern.

Keine der beiden Berechtigungen kann Auszahlungen auslösen: Eine Auszahlung auszuführen oder zu wiederholen, braucht eine angemeldete Dashboard-Sitzung eines Owners und liefert für API-Schlüssel immer 403 interactive_session_required.

Der Wert "read_write" wird ebenfalls akzeptiert und bedeutet dasselbe wie "write".

Nimm einen reinen Leseschlüssel für jedes Drittanbieter-Tool, dem du nicht voll vertraust (Analyse-Dashboards, BI-Tools, ETL-Jobs, die nur Daten herauskopieren). Schreibrechte gibst du deinem eigenen Anwendungscode.

Einen Schlüssel rotieren

Beim Rotieren werden Bearer-Schlüssel und Signatur-Secret ausgetauscht, Name und Berechtigungen bleiben gleich. Klicke neben einem Schlüssel auf Rotieren. Ein neuer Bearer-Schlüssel und ein neues Signatur-Secret im Klartext werden GENAU EINMAL angezeigt. Die alten Werte funktionieren sofort nicht mehr. Es gibt keine Übergangszeit; rotiere also in einem Wartungsfenster, wenn du viele Integrationen aktualisieren musst.

Rotiere, wenn:

• ein Teammitglied mit Zugriff auf den Schlüssel das Team verlässt.
• ein Schlüssel versehentlich in ein öffentliches Repository committet wurde.
• deine Sicherheitsrichtlinie eine vierteljährliche Rotation vorsieht.

Einen Schlüssel widerrufen

Ein Widerruf deaktiviert einen Schlüssel dauerhaft. Klicke auf Widerrufen. Der Schlüssel funktioniert sofort nicht mehr, und das lässt sich nicht rückgängig machen. Brauchst du wieder Zugriff, erstelle einen neuen Schlüssel.

Prüfpfad

Jede Änderung an Schlüsseln wird automatisch festgehalten, du siehst also immer, wer was getan hat. Erstellen, Rotieren und Widerrufen stehen im Audit-Log unter /dashboard/settings/audit-log. Der Eintrag nennt das Teammitglied, das die Aktion ausgeführt hat. Einträge zum Erstellen enthalten Name und Präfix des Schlüssels (nicht den Klartext); Einträge zum Rotieren und Widerrufen verweisen auf die ID des Schlüssels.

Wo Schlüssel sichtbar sind

Die Liste unter /dashboard/settings/api-keys und GET /api/api-keys (nur mit Dashboard-Sitzung; dieser Endpunkt verlangt eine Anmeldesitzung im Browser und lässt sich nicht mit einem API-Schlüssel aufrufen) zeigt jeden Schlüssel so:

• id
• name
• keyPrefix (die ersten 16 Zeichen des Bearer-Schlüssels; unbedenklich für Logs)
• scopes (Array mit "read" und/oder "write")
• lastUsedAt (Zeitstempel, null, wenn sich der Schlüssel noch nie authentifiziert hat)
• expiresAt (null, wenn er nicht abläuft)
• revokedAt (null, wenn er aktiv ist)
• createdAt

Der Bearer-Schlüssel im Klartext ist nach dem Erstellen nie wieder abrufbar. Die IP-Adresse, von der aus ein Schlüssel zuletzt genutzt wurde, geben wir in der API und in der Liste im Dashboard nicht zurück. IP-Adressen landen stattdessen im Audit-Log, und dort sehen sie nur Owner mit JWT-Dashboard-Sitzung; für Aufrufe mit API-Schlüssel werden sie entfernt (siehe Referenz).

Signatur-Secret

Das Signatur-Secret dient für HMAC-SHA256-Signaturen an den S2S-Endpunkten. Es ist vom Bearer-Schlüssel getrennt, weil:

• der Bearer-Schlüssel nachweist, wer die Anfrage stellt.
• das Signatur-Secret nachweist, dass der Body der Anfrage unterwegs nicht verändert wurde.

Manche Integrationen brauchen nur den Bearer-Schlüssel (die meisten CRUD-Endpunkte). Das S2S-Tracking braucht beides.

Das Signaturformat findest du unter S2S-Tracking.

Signatur-Secret für Webhooks

Ausgehende Webhook-Endpunkte (an die Rekomi Ereignisse per POST schickt) haben ihre eigenen Signatur-Secrets, getrennt von den Signatur-Secrets der API-Schlüssel oben. Wenn du unter /dashboard/settings/webhooks einen Webhook-Endpunkt anlegst, bekommst du ein einmal angezeigtes Signatur-Secret, mit dem du eingehende Payloads auf deinem Server prüfst.

Die beiden Secrets sind nicht austauschbar. Nimm für jede Richtung das richtige.

Bewährte Vorgehensweisen

• Speichere Schlüssel in einem Secrets-Manager (1Password, AWS Secrets Manager, HashiCorp Vault). Committe sie nie in die Versionsverwaltung. Wir scannen unsere eigenen Repositorys mit gitleaks; das solltest du auch tun.
• Nutze getrennte Schlüssel pro Deployment deines eigenen Stacks (einen für dein Produktions-Backend, einen für dessen Staging-Kopie; beide sprechen mit demselben Rekomi-Workspace, da Rekomi keine eigene Staging-Umgebung hat). Nutze die Berechtigungen (einen read-Schlüssel fürs Monitoring, einen read_write-Schlüssel für den Anwendungscode).
• Rotiere vierteljährlich, auch ohne Vorfall.

Wenn du einen Schlüssel verlierst

Rotiere ihn im Dashboard. Kommst du nicht ins Dashboard (weil dein Konto kompromittiert ist), schreib uns im Chat auf einer beliebigen Seite von rekomi.com (der Messenger sitzt unten rechts, ohne Anmeldung), und wir widerrufen den Schlüssel serverseitig.