Come ottengo una chiave API?

Ogni chiamata API porta la chiave dell'organizzazione in un header HTTP:

Authorization: Bearer lpdc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Non c'è un passaggio di login né un token separato da ottenere: la chiave va su ogni richiesta.

• Un'organizzazione può avere più chiavi attive contemporaneamente: è così che ne ruoti una senza interruzioni di servizio. Emetti quella nuova, aggiorni i chiamanti, revochi quella vecchia.
• Ogni chiave scade. Scegli una durata quando la emetti (30, 90, 180, 365 o 730 giorni, 90 per impostazione predefinita); non esiste un'opzione illimitata né un periodo di tolleranza dopo la scadenza: una chiave scaduta risponde esattamente come una revocata. Emetti la chiave successiva prima che la vecchia scada.
• La revoca ha effetto immediato: la richiesta successiva riceve già INVALID_API_KEY. Non c'è finestra di tolleranza.
• Una chiave porta degli scope: ciò per cui può essere usata, scelti all'emissione, un permesso alla volta, con una casella per ciascuno (composizione, lettura, download, gestione dei modelli, invio per la firma, il flusso in una chiamata, lotti, consumi, chiamate di test), e mai ampliati in seguito: i permessi di una chiave possono solo restringersi. Chiamare qualcosa fuori dai suoi scope risponde TOKEN_SCOPE_NOT_ALLOWED; emetti una nuova chiave più ampia invece di provare a modificare quella vecchia.
• Una chiave ha un nome, obbligatorio e diverso dal nome di ogni altra chiave attiva della tua organizzazione (billing-export, crm-sync); il nome di una chiave revocata può essere riutilizzato. Le chiavi si emettono solo dalla console, nella pagina Chiavi API: mai da noi per conto tuo.
• Le chiavi sono conservate solo come hash. Nemmeno un amministratore può rileggere una chiave emessa: la console ne mostra solo gli ultimi quattro caratteri, per distinguere tra loro più chiavi aperte.

La chiave iniziale

Un nuovo account riceve una chiave iniziale, chiamata hello-world, invece di una con accesso completo. Contiene esattamente ciò che serve alla prima chiamata: documents:compose, documents:read, documents:download, usage:* e isTest (la sandbox). Non può gestire i modelli, inviare per la firma, eseguire il flusso né inviare un lotto, e scade dopo poco tempo (90 giorni, salvo che l'abbiamo cambiato). Un coordinatore crea una chiave completa con un clic nella pagina Chiavi API della console; nessuna chiave esistente cambia quando lo fa. Chiamare qualcosa che la chiave iniziale non contiene risponde TOKEN_SCOPE_NOT_ALLOWED e indica lo scope mancante in details.missingScopes.

Quale scope serve a ogni chiamata

Una chiave deve avere uno scope del gruppo della chiamata e lo scope specifico della chiamata; lo scope di gruppo (documents:*, signatures:*, bulk:*) soddisfa ogni chiamata del suo gruppo. Un rifiuto elenca lo scope che ti mancava. L'invio di un lotto ne richiede due: bulk:submit esegue il lotto e lo scope della singola chiamata (documents:compose, signatures:ses o flow:*) autorizza ciò che vi si fa, quindi un lotto non è mai un modo per aggirare uno scope. Se mancano entrambi, la risposta indica il primo, bulk:submit; una volta concesso, indica l'altro.

Chiamata	Scope
POST /api/v1/compose/documents/generate	documents:compose
POST /api/v1/compose/documents/validate	documents:compose
GET /api/v1/compose/documents/{id} (il PDF), /api/v1/compose/documents/{id}/download-links	documents:download
POST o DELETE /api/v1/compose/files	documents:compose
GET /api/v1/compose/files	documents:read
/api/v1/compose/templates/*	documents:templates
/api/v1/sign/*	signatures:ses
POST /api/v1/bulk/compose	bulk:submit e documents:compose
POST /api/v1/bulk/sign	bulk:submit e signatures:ses
POST /api/v1/bulk/flow	bulk:submit e flow:*
POST /api/v1/bulk/files, annullare o ritentare un lotto	bulk:submit (un nuovo tentativo richiede anche lo scope dell'operazione del lotto)
GET /api/v1/bulk/jobs*	bulk:read
/api/v1/flow/*	flow:*
GET /api/v1/usage, GET /api/v1/callback-environments	nessuno: leggibili da qualsiasi chiave attiva
Una richiesta con "isTest": true	isTest, in aggiunta a quanto sopra

Avvisi di scadenza

Scriviamo ai coordinatori dell'organizzazione una volta a 30, 7 e 1 giorno dalla scadenza di una chiave, con la data esatta e un link per creare la successiva. Una chiave la cui intera durata non supera una soglia salta quell'avviso. Non c'è periodo di tolleranza: al secondo indicato la chiave smette di funzionare.

Un limite per una singola chiave

Oltre al limite di richieste al minuto dell'organizzazione, un coordinatore può dare a una singola chiave un limite proprio, nella pagina Chiavi API. Una chiave oltre il suo limite viene rifiutata con RATE_LIMIT_EXCEEDED (HTTP 429, i consueti header Retry-After e X-RateLimit-*, e details.limitedBy: "token") prima che la richiesta venga conteggiata per l'organizzazione, così un'integrazione guasta non può consumare il margine delle altre. Il limite dell'organizzazione vale comunque per ogni chiave. Senza un limite impostato, la chiave segue un valore predefinito della piattaforma, che è nessun limite.

Cosa può chiamare una chiave

La suite è composta da tre prodotti, venduti separatamente, e un'organizzazione può averne qualsiasi combinazione:

Superficie	Prefisso	Risponde anche su
Composer Fly — composizione di documenti	/api/v1/compose/*	/api/v1/documents/* /api/v1/templates/*
Signer Fly — firma elettronica	/api/v1/sign/*	/api/v1/signatures/*
Document Fly — il flusso in una chiamata	/api/v1/flow/*	—

Una chiamata a un prodotto non attivo risponde 403 SUITE_NOT_ENABLED, lo indica in details.suite ed elenca ciò che hai attivo in details.enabled. Non viene addebitato nulla, e nessun cambio di chiave lo risolve: è un abbonamento, non una credenziale. Un coordinatore vede lo stesso elenco in Impostazioni, nella propria console.

Vale solo per le chiavi API. La tua console non ne è toccata: modelli, documenti e firme restano visibili lì, qualunque cosa sia disattivata qui.