Agent SDK Geheimnisse & HMAC Signieren
Schützen Sie die Anmeldeinformationen des Agenten API und verstehen Sie, wie der SDK zeitgestempelte, abspielsichere HMAC-SHA256-Anfragesignaturen generiert.
Agent SDK-Anfragen werden mit einem Partner-API-Geheimnis authentifiziert. Bewahren Sie dieses Geheimnis in einem vertrauenswürdigen Backend-Dienst auf und lassen Sie SDK wann immer möglich Signaturfelder generieren.
Zwei Signaturprotokolle
Beim Signieren mit Agent SDK werden sortierte Anforderungsfelder, ein sekundenbasierter Zeitstempel und eine Nonce verwendet. Direkte Developer API-Anfragen verwenden den separaten Prozess, der in beschrieben wird Signieren anfordern. Verwenden Sie nicht ein Nutzlastformat für ein anderes.
Unterzeichnungsregel
Für Agent SDK-Anfragen:
- Schließen Sie das Feld
signaus. - Lassen Sie Felder mit leeren Werten weg.
- Sortieren Sie die verbleibenden Feldnamen in der Reihenfolge ASCII.
- Verknüpfen Sie die Felder als
k=v&k2=v2. - Berechnen Sie die hexadezimale Signatur HMAC-SHA256 mit
apiSecret.
Array-Werte werden als kompakte JSON serialisiert, bevor sie der Signierungsnutzlast hinzugefügt werden. Beispielsweise signiert platformUserIds als ["1188041528"] und ergibt platformUserIds=["1188041528"] in der Nutzlast k=v. Behalten Sie die Reihenfolge der Array-Elemente, doppelte Anführungszeichen und String-IDs bei. Fügen Sie keine Formatierungsleerzeichen ein und verwenden Sie nicht Java List.toString() (z. B. [1188041528]). Der SDK übernimmt diese Serialisierung automatisch.
Der SDK sollte diesen Wert aus denselben Daten erstellen, die er sendet. Das Ändern eines signierten Felds nach der Signaturgenerierung führt dazu, dass die Überprüfung fehlschlägt.
SDK-verwaltete Felder
Geheimspeicher
- Laden Sie
apiSecretvon einem Backend-Secret-Manager oder einer geschützten Laufzeitkonfiguration. - Platzieren Sie das Geheimnis niemals in Frontend-Paketen, mobilen Apps, Desktop-Clients, Screenshots oder Support-Tickets.
- Halten Sie die Anmeldeinformationen für Entwicklung, Staging und Produktion getrennt.
- Beschränken Sie den Zugriff auf die Dienste und Betreiber, die dies erfordern.
- Schwärzen Sie Anforderungssignaturen, Autorisierungswerte und Geheimnisse aus Protokollen.
- Widerrufen und ersetzen Sie Anmeldeinformationen, wenn der Verdacht besteht, dass Sie gefährdet sind.
Takt- und Wiedergabeschutz
Das SDK umfasst timestamp und nonce, um das Wiederholungsrisiko zu verringern. Halten Sie die Backend-Uhren synchronisiert und verwenden Sie keine manuell erstellte Nonce wieder. Wenn die Signaturvalidierung fehlschlägt, überprüfen Sie das konfigurierte Geheimnis, die Serverzeit, die serialisierten Felder und die Umgebung, bevor Sie es erneut versuchen.