Erstellen Sie API-Schlüssel unter Entwickler, geben Sie jedem Dienst einen eigenen Schlüssel mit engem Zugriff und rotieren Sie ihn ohne Ausfallzeit.
Entwickler → API-Schlüssel, bezogen auf die ausgewählte Anwendung. Jede Anwendung hat einen Primär-Schlüssel, und Sie können weitere erstellen, einen pro Dienst, jeden mit eigenem Zugriff und eigenem Ablaufdatum. Ein Schlüssel ist ein serverseitiges Secret: niemals im Frontend-Code oder in einem App-Bundle.
Ihre API-Schlüssel befinden sich unter Entwickler → API-Schlüssel in der Konsole, bezogen auf die Anwendung, in der Sie gerade arbeiten. Behandeln Sie jeden Schlüssel wie ein Passwort: Er gewährt 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 Anwendung über die Anwendungskarte oben in der Seitenleiste. Jede Anwendung hat ihre eigenen Schlüssel.
- Entwickler und dann API-Schlüssel öffnen
Der Tab Schlüssel listet jeden Schlüssel auf, beginnend mit dem Primär-Schlüssel, mit seinem Zugriff, seiner letzten Verwendung und seinem Ablaufdatum.
#Einen Schlüssel erstellen
Geben Sie jedem Dienst, der Didit aufruft, einen eigenen Schlüssel, damit Sie sehen, was jeder einzelne tut, und ihn einzeln widerrufen können.
- Auf Schlüssel erstellen klicken
Unter Entwickler → API-Schlüssel.
- Benennen und Umgebung wählen
Benennen Sie den Schlüssel nach dem Dienst, der ihn verwenden wird, wählen Sie Live (echte Verifizierungen, kostenpflichtig) oder Sandbox (Testdaten, nie kostenpflichtig; der Schlüssel wird in der Sandbox-Anwendung Ihrer Organisation erstellt) und legen Sie fest, wann er abläuft: nie, nach 30 Tagen, 90 Tagen oder einem Jahr, oder an einem Datum Ihrer Wahl.
- Den Zugriff wählen
Vollzugriff liest und schreibt alles, für Ihr eigenes Backend. Nur Lesezugriff sieht Sessions, Entscheidungen und Medien, kann aber nichts ändern, für einen Partner, der nur Ergebnisse braucht. Mit Benutzerdefiniert wählen Sie Ressource für Ressource selbst. Deaktivieren Sie Medien einbeziehen, wenn der Dienst nur die Entscheidung braucht und keine Ausweisbilder, Selfies, Videos oder PDF-Berichte.
- Prüfen und das Secret kopieren
Das vollständige Secret wird nur einmal angezeigt, wenn der Schlüssel erstellt wird. Kopieren Sie es direkt in Ihren Secret-Manager.
Der Primär-Schlüssel ist das ursprüngliche Secret der Anwendung. Er hat immer Vollzugriff und kann rotiert, aber nicht widerrufen werden.
#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, so viele Sie brauchen |
| Webhook Signing Secret | Bestätigt, dass ein eingehender Webhook wirklich von Didit stammt | Pro Webhook-Endpunkt |
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. Schalten Sie die Konsole auf Sandbox und erstellen Sie dort einen Schlüssel, oder wählen Sie beim Erstellen Sandbox als Umgebung. Sandbox-Sessions simulieren jede externe Prüfung, werden nie abgerechnet und berühren keine echten Nutzerdaten.
Ein Schlüssel gehört zu einer Anwendung und damit zur Umgebung dieser Anwendung: Ein Sandbox-Schlüssel erstellt nie eine Live-Verifizierung, und ein Live-Schlüssel erstellt nie eine Sandbox-Verifizierung. Es lohnt 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, öffnen Sie ihn und wählen Sie Schlüssel rotieren. Sie erhalten ein neues Secret, und das alte funktioniert noch 24 Stunden weiter, sodass Sie das neue Secret ohne Ausfallzeit ausrollen können. Danach liefert jede Anfrage mit dem alten Secret einen 401.
Wenn ein Schlüssel sofort aufhören muss zu funktionieren, wählen Sie stattdessen Schlüssel widerrufen. Das Widerrufen stoppt ihn sofort und lässt sich nicht rückgängig machen. Der Primär-Schlüssel kann nur rotiert werden.
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, abgelaufen, widerrufen oder wurde vor mehr als 24 Stunden rotiert | Prüfen Sie den Schlüssel unter Entwickler → API-Schlüssel für diese Anwendung. Achten Sie auf überflüssige Leerzeichen oder Anführungszeichen, und prüfen Sie, 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), ein Zugriff, den der Schlüssel nicht erhalten hat (zum Beispiel ein Schlüssel mit Lesezugriff, der schreiben will), 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 verwenden Sie stattdessen einen ihrer Schlüssel. Vollständige Übersicht: API-Fehler und was sie bedeuten.
#Einschränken, was ein Schlüssel darf
Wählen Sie den Zugriff beim Erstellen des Schlüssels und ändern Sie ihn später mit Zugriff bearbeiten (das Secret bleibt gleich; der Zugriff des Primär-Schlüssels lässt sich nicht bearbeiten). Nur Lesezugriff verhindert, dass ein Partner etwas ändert, Benutzerdefiniert legt pro Ressource Keiner, Lesen oder Schreiben fest (Sessions, Entscheidungen, Medien, Personen, Unternehmen und mehr), und wenn Medien einbeziehen ausgeschaltet bleibt, kann ein Dienst keine Ausweisbilder, Selfies, Videos und PDF-Berichte herunterladen. Unter Beschränkungen lässt sich ein Schlüssel außerdem auf bestimmte Workflows, nur auf genehmigte Sessions oder auf eine Liste von IP-Adressen begrenzen: Eine Anfrage von außerhalb der Liste wird mit 403 beantwortet, und eine Session außerhalb der Workflows oder Status des Schlüssels mit 404. Öffnen Sie einen Schlüssel, um genau zu sehen, was er darf; ein Schlüssel kann nie mehr, als sein Zugriff erlaubt.
#Wer in Ihrem Team Schlüssel sehen kann
Die Sichtbarkeit von Schlüsseln richtet sich nach der Rolle: Zum Ansehen der Seite ist die Berechtigung nötig, API-Schlüssel zu lesen, die in der Rolle Entwickler enthalten ist. Secrets bleiben in der Konsole maskiert. Wenn ein Teammitglied die Seite nicht findet, prüfen Sie zuerst seine Rolle, bevor Sie es melden. Siehe Teammitglieder einladen und Rollen festlegen.
#Jeder Aufruf wird protokolliert
API-Schlüssel-Anfragen erscheinen im Audit-Protokoll, zugeordnet dem Schlüssel 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.
Kommen Sie nicht weiter? Sprechen Sie mit einem Menschen.
Geben Sie Ihre Organisations-ID und die Session-ID an, um die es geht.