Authentification avec l'API
GraphQL prend en charge deux modes d'authentification :
| Mode | Couverture | En-tête | Idéal pour |
|---|---|---|---|
| OAuth 2.0 | Sous-ensemble pris en charge uniquement (les opérations API-key, sauf generateComponentToken) | Authorization: Bearer <access-token> | Intégrations agissant au nom d'un utilisateur Legalesign, qui se connecte et consent |
| Clé API | Sous-ensemble pris en charge uniquement | Authorization: Bearer <api-key> | Automatisation côté serveur et flux courants d'envoi/lecture |
Les deux modes prennent en charge le même ensemble d'opérations. Un jeton OAuth agit en tant qu'utilisateur qui l'a autorisé, avec les permissions de cet utilisateur.
Authentification par clé API
Créez une clé API activée pour GraphQL dans le Developer Portal, puis envoyez-la en tant que jeton bearer :
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 nécessite seulement
Authorization: Bearer. Aucun en-têtex-organisationou autre en-tête personnalisé n’est requis.
Vérifiez les opérations GraphQL prises en charge et les badges d'authentification sur les pages de référence des requêtes et mutations avant d'utiliser une opération avec une clé API.
Authentification OAuth 2.0
OAuth 2.0 permet à votre application d'agir au nom d’un utilisateur Legalesign spécifique, pour les opérations supportées par les clés API, à l’exception de generateComponentToken (voir les opérations GraphQL prises en charge). L'utilisateur se connecte et consent explicitement. Votre application ne gère jamais son mot de passe.
Enregistrez un client OAuth dans le Developer Portal, puis suivez le guide client OAuth pour les étapes complètes d’intégration. Votre serveur s’authentifie auprès du point de terminaison de jeton avec le secret client, ainsi que PKCE.
Une fois que vous avez un jeton d'accès, utilisez-le de la même manière qu’une clé API :
POST /graphql HTTP/1.1
Host: graphql.uk.legalesign.com
Content-Type: application/json
Authorization: Bearer eyJ...
{"query": "{ user { id email } }"}
Les jetons d'accès expirent après une heure. Utilisez le jeton de rafraîchissement pour en obtenir un nouveau sans que l’utilisateur ait à se réauthentifier. Un jeton de rafraîchissement expire s'il n'est pas utilisé depuis 30 jours, et l'autorisation de l'utilisateur dans son ensemble dure 12 mois à compter de sa dernière approbation de votre application, après quoi l'utilisateur doit réautoriser. Les jetons de rafraîchissement tournent à chaque usage, donc rafraîchissez depuis un seul endroit à la fois et enregistrez le nouveau jeton à chaque fois.
Les jetons OAuth sont acceptés uniquement par l’API GraphQL, pas par l’API REST. Un jeton agit avec les propres permissions de l'utilisateur autorisé et n’est actuellement pas limité aux données de votre organisation. Consultez le guide client OAuth pour comprendre ce que cela implique avant d’enregistrer un client.
Autorisation des widgets et composants
Les widgets authentifiés tels que le Document Viewer et le Signer nécessitent un jeton à courte durée de vie passé à leur attribut token. Utilisez une clé API pour appeler generateComponentToken côté serveur et passez le jeton retourné au widget.
Consultez Autorisation des widgets pour le flux complet et les conseils de sécurité pour le navigateur.