Vai al contenuto principale

Autenticarsi con l'API

GraphQL supporta due modalità di autenticazione:

ModalitàCoperturaIntestazioneIdeale per
OAuth 2.0Solo sottoinsieme supportato (le operazioni con API-key, eccetto generateComponentToken)Authorization: Bearer <access-token>Integrazioni che agiscono per conto di un utente Legalesign, che effettua il login e dà il consenso
API KeySolo sottoinsieme supportatoAuthorization: Bearer <api-key>Automazione lato server e flussi comuni di invio/lettura

Entrambe le modalità supportano lo stesso insieme di operazioni. Un token OAuth agisce come l'utente che lo ha autorizzato, con le sue permessi.

Autenticazione con API Key​

Crea una API key abilitata per GraphQL nel Developer Portal, quindi inviala come token 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 necessita solo di Authorization: Bearer. Non sono richiesti x-organisation o altre intestazioni personalizzate.

Controlla le operazioni GraphQL supportate e i badge di autorizzazione nelle pagine di riferimento di query e mutation prima di usare un'operazione con una API key.

Autenticazione OAuth 2.0​

OAuth 2.0 consente alla tua applicazione di agire per conto di un utente specifico di Legalesign, per le operazioni supportate dalle API key, eccetto generateComponentToken (vedi le operazioni GraphQL supportate). L'utente effettua il login e dà esplicitamente il consenso. La tua applicazione non gestisce mai la loro password.

Registra un client OAuth nel Developer Portal, quindi segui la guida al client OAuth per tutti i passaggi di integrazione. Il tuo server si autentica al token endpoint con il client secret, oltre che con PKCE.

Una volta ottenuto un token di accesso, usalo esattamente come una API key:

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

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

I token di accesso scadono dopo un’ora. Usa il token di refresh per ottenerne uno nuovo senza che l'utente debba riautenticarsi. Un token di refresh scade se non viene usato per 30 giorni, e l'autorizzazione complessiva dell'utente dura 12 mesi dal momento in cui ha approvato l'applicazione l'ultima volta, dopo di che l'utente deve autorizzare nuovamente. I token di refresh ruotano ad ogni uso, quindi aggiorna da un solo punto alla volta e salva ogni volta il nuovo token.

nota

I token OAuth sono accettati solo dall'API GraphQL, non dall'API REST. Un token agisce con i permessi propri dell'utente autorizzato, e attualmente non è limitato ai dati della tua organizzazione. Consulta la guida al client OAuth per capire cosa significa prima di registrare un client.

Autorizzazione di Widget e Componenti​

I widget autenticati come il Document Viewer e il Signer richiedono un token a breve durata passato all'attributo token. Usa una API key per chiamare generateComponentToken lato server e passa il token restituito al widget.

Consulta Autorizzazione Widget per il flusso completo e le indicazioni sulla sicurezza nel browser.

Export This Article

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