Zum Hauptinhalt springen

Authentifizierung mit der API

GraphQL unterstützt zwei Authentifizierungsmodi:

ModusAbdeckungHeaderAm besten geeignet für
OAuth 2.0Nur unterstützter Teil (die API-Key-Operationen, außer generateComponentToken)Authorization: Bearer <access-token>Integrationen im Auftrag eines Legalesign-Benutzers, der sich anmeldet und zustimmt
API-SchlüsselNur unterstützter TeilAuthorization: Bearer <api-key>Serverseitige Automatisierung und gängige Sende-/Lesevorgänge

Beide Modi unterstützen denselben Satz von Operationen. Ein OAuth-Token verhält sich wie der Benutzer, der es autorisiert hat, mit dessen Berechtigungen.

API-Schlüssel-Authentifizierung​

Erstellen Sie einen GraphQL-fähigen API-Schlüssel im Developer Portal und senden Sie ihn dann als Bearer-Token:

POST /graphql HTTP/1.1
Host: graphql.uk.legalesign.com
Content-Type: application/json
Authorization: Bearer ak_<environment>_<key-id>.<secret>

{"query": "{ user { id email } }"}

GraphQL benötigt nur Authorization: Bearer. Keine x-organisation oder andere benutzerdefinierte Header sind erforderlich.

Überprüfen Sie die unterstützten GraphQL-Operationen und die Auth-Badges auf den Query- und Mutation-Referenzseiten, bevor Sie eine Operation mit einem API-Schlüssel verwenden.

OAuth 2.0-Authentifizierung​

OAuth 2.0 ermöglicht es Ihrer Anwendung, im Auftrag eines bestimmten Legalesign-Benutzers zu handeln, für die Operationen, die API-Schlüssel unterstützen, außer generateComponentToken (siehe die unterstützten GraphQL-Operationen). Der Benutzer meldet sich an und stimmt explizit zu. Ihre Anwendung verarbeitet niemals dessen Passwort.

Registrieren Sie einen OAuth-Client im Developer Portal und folgen Sie dann dem OAuth-Client-Leitfaden für die vollständigen Integrationsschritte. Ihr Server authentifiziert sich am Token-Endpunkt mit dem Client-Geheimnis sowie PKCE.

Sobald Sie ein Access-Token haben, verwenden Sie es genauso wie einen API-Schlüssel:

POST /graphql HTTP/1.1
Host: graphql.uk.legalesign.com
Content-Type: application/json
Authorization: Bearer eyJ...

{"query": "{ user { id email } }"}

Access-Tokens laufen nach einer Stunde ab. Verwenden Sie das Refresh-Token, um ein neues zu erhalten, ohne dass sich der Benutzer erneut authentifizieren muss. Ein Refresh-Token verfällt, wenn es 30 Tage lang nicht verwendet wurde, und die Autorisierung des Benutzers insgesamt gilt 12 Monate ab dem Zeitpunkt der letzten Genehmigung Ihrer Anwendung, danach autorisiert der Benutzer erneut. Refresh-Tokens rotieren bei jeder Verwendung, also führen Sie die Aktualisierung jeweils nur an einem Ort durch und speichern Sie jedes Mal das neue Token.

Hinweis

OAuth-Tokens werden nur von der GraphQL-API akzeptiert, nicht von der REST-API. Ein Token agiert mit den Berechtigungen des autorisierten Benutzers und ist derzeit nicht auf die Daten Ihrer Organisation beschränkt. Siehe den OAuth-Client-Leitfaden für die Bedeutung dessen, bevor Sie einen Client registrieren.

Widget- und Komponentenautorisierung​

Authentifizierte Widgets wie der Document Viewer und der Signer benötigen ein kurzlebiges Token, das an ihr token-Attribut übergeben wird. Verwenden Sie einen API-Schlüssel, um serverseitig generateComponentToken aufzurufen und das zurückgegebene Token an das Widget zu übergeben.

Siehe Widget-Autorisierung für den kompletten Ablauf und Sicherheitshinweise für den Browser.

Export This Article

Save a copy of this page as PDF or plain text.