Ihre API-Schlüssel verwalten
Finden Sie Ihren API-Schlüssel unter API & Webhooks in der Konsole, halten Sie ihn serverseitig, nutzen Sie für Tests eine separate Sandbox-Anwendung, und beheben Sie 401- und 403-Fehler.
API & Webhooks, bezogen auf die ausgewählte Anwendung. Ein Schlüssel pro Anwendung, und der Schlüssel ist die Umgebung - es gibt keinen separaten Testschlüssel auf einer Live-Anwendung. Es ist ein serverseitiges Secret: niemals im Frontend-Code oder in einem App-Bundle.
Ihr API-Schlüssel befindet sich unter API & Webhooks in der Seitenleiste der Konsole, bezogen auf die Anwendung, in der Sie gerade arbeiten. Behandeln Sie ihn wie ein Passwort - er gewährt vollen API-Zugriff im Namen dieser Anwendung.
#Ihren Schlüssel finden
- Bei der Business-Konsole anmelden
Gehen Sie zu business.didit.me und melden Sie sich an.
- Ihre Anwendung auswählen
Wählen Sie die gewünschte Anwendung aus dem Dropdown oben in der Konsole. Jede Anwendung hat ihren eigenen Schlüssel.
- API & Webhooks öffnen
Hier finden Sie Ihren API-Schlüssel, zusammen mit Ihren Webhook-Zielen und deren Signing Secrets.
- Create API key stellt einen neuen Schlüssel aus; Schlüssel gelten pro Anwendung.
- Das Secret wird hier einmalig angezeigt - kopieren Sie es in Ihren eigenen Secret-Speicher.
- Rotate secret ersetzt das Secret, ohne den Namen des Schlüssels zu ändern.
- Last used zeigt Ihnen, ob ein Schlüssel noch aktiv ist oder vergessen wurde, bevor Sie ihn widerrufen.
#API-Schlüssel und Signing Secret sind zwei verschiedene Dinge
Das lohnt sich klar zu sagen, denn eine Verwechslung erzeugt verwirrende Fehler:
| Wofür es ist | Wo | |
|---|---|---|
| API-Schlüssel | Authentifiziert Ihre Aufrufe an Didit, im Header x-api-key | Pro Anwendung |
| Webhook Signing Secret | Bestätigt, dass ein eingehender Webhook wirklich von Didit stammt | Pro Ziel |
Wenn Sie das Signing Secret als API-Schlüssel senden, entsteht ein 401. Wenn Sie einen Webhook mit Ihrem API-Schlüssel verifizieren, entsteht eine Signaturabweichung. Beides kommt häufig vor.
Ihr API-Schlüssel ist geheim. Bringen Sie ihn niemals in Frontend-Code, ein öffentliches Repository oder ein mobiles App-Bundle - halten Sie ihn ausschließlich serverseitig. Ein Schlüssel in einem ausgelieferten App-Bundle ist ein Schlüssel, den ein Angreifer hat. Siehe API-Authentifizierung.
#Einen Schlüssel zum Testen bekommen
Sie testen nicht gegen die Produktivumgebung. Erstellen Sie eine separate Anwendung im Sandbox-Modus - Sandbox-Sessions simulieren jede externe Prüfung, werden nie abgerechnet und berühren keine echten Nutzerdaten. Nutzen Sie deren Schlüssel während des Aufbaus, und behalten Sie eine separate Live-Anwendung für echte Verifizierungen.
Es gibt keinen "Testschlüssel" auf einer Live-Anwendung. Der Schlüssel ist die Umgebung, daher lohnt es sich, Ihre Schlüssel dort, wo Sie Ihre Secrets ablegen, eindeutig zu benennen. Siehe Testen in der Sandbox.
#Ihren Schlüssel rotieren
Wenn ein Schlüssel offengelegt worden sein könnte, erzeugen Sie ihn auf derselben Seite API & Webhooks neu. Das Neuerzeugen macht den alten Schlüssel sofort ungültig, aktualisieren Sie ihn also zuerst überall dort, wo er verwendet wird - sonst beginnt Ihr Produktivverkehr in dem Moment zu scheitern, in dem Sie auf die Schaltfläche klicken.
Eine regelmäßige Rotation nach Zeitplan ist gute Praxis. Planen Sie sie wie ein Deployment, nicht wie einen einzelnen Klick.
#401 und 403 beheben
| Fehler | Ursache | Lösung |
|---|---|---|
401 | Der Schlüssel fehlt, ist fehlerhaft formatiert oder wurde neu erzeugt | Kopieren Sie den aktuellen Schlüssel aus API & Webhooks für diese Anwendung. Prüfen Sie auf überflüssige Leerzeichen oder Anführungszeichen, und dass Sie kein Signing Secret eingefügt haben |
403 | Der Schlüssel ist gültig, aber dieser Aufruf ist nicht erlaubt | Meist die falsche Anwendung, ein Sandbox-Feld auf einem Live-Schlüssel (oder umgekehrt), eine Berechtigung, die Ihrem Schlüssel fehlt, oder eine Funktion, die in Ihrem Konto nicht aktiviert ist |
Ein 403 bei einem bestimmten Workflow bedeutet fast immer, dass der Schlüssel zu einer anderen Anwendung gehört als der, die diesen Workflow besitzt. Wechseln Sie die Anwendung in der Konsole und kopieren Sie stattdessen deren Schlüssel. Vollständige Übersicht: API-Fehler und was sie bedeuten.
#Einschränken, was ein Schlüssel darf
Wenn Sie einschränken möchten, welche Datenkategorien ein Schlüssel erreichen kann - etwa um zu verhindern, dass ein Dienst Dokumentbilder abruft - ist das eine Frage der Berechtigungen und keine Schlüsseleinstellung, und was verfügbar ist, hängt von Ihrem Konto ab. Fragen Sie den Support, statt anzunehmen, ein Schlüssel sei uneingeschränkt oder eingeschränkt; beide Annahmen sind in entgegengesetzte Richtungen riskant.
#Wer in Ihrem Team Schlüssel sehen kann
Die Sichtbarkeit von Schlüsseln richtet sich nach der Rolle. Die Rolle Developer deckt API-Schlüssel ab; Reader nicht. Wenn ein Teammitglied die Seite nicht findet, prüfen Sie zuerst seine Rolle. Siehe Teammitglieder einladen und Rollen festlegen.
#Jeder Aufruf wird protokolliert
API-Schlüssel-Anfragen erscheinen in den Audit-Protokollen, zugeordnet der Anwendung statt einer Person - genau deshalb macht ein Schlüssel, der von mehreren Diensten gemeinsam genutzt wird, einen Vorfall schwerer untersuchbar. Ein Schlüssel pro Konsument lässt sich leichter nachvollziehen. Siehe Audit-Protokolle nutzen.