Creare una chiave API

Le chiavi API permettono a un altro sistema di comandare AssinaJá — il suo ERP che crea documenti, o un assistente IA che lavora tramite l’interfaccia MCP. Ne crei una per ogni sistema esterno o assistente IA, con autorizzazioni limitate a ciò di cui quella integrazione ha bisogno.

Impostazioni → Sviluppatori ha le schede Generale, Chiavi API, Webhook, Integrazioni e Archiviazione — le ultime due solo per il Proprietario e l’Amministratore. Generale si apre per prima, con gli indirizzi dell’API pubblica e del Server MCP e il link Apri la documentazione dell’API.

Le chiavi si trovano in Chiavi API, e le gestisce solo il Proprietario dell’organizzazione. Con un altro ruolo, la scheda si apre ma non mostra le chiavi.

Una chiave per integrazione

Crei una chiave per ogni sistema esterno che si integra con l’API pubblica (header X-Api-Key). Ogni chiave può essere sospesa o eliminata singolarmente, senza influire sulle altre integrazioni.

È questo il motivo della regola: una chiave condivisa non può essere revocata senza interrompere tutto ciò che la usa. Una chiave per sistema permette di disattivare un’integrazione e lasciare funzionanti le altre.

Crearne una

Scelga Nuova chiave API.

1. Nome — le dia il nome del sistema che la userà, per esempio Gestionale ERP. Se vuole, aggiunga una Descrizione.
2. Data di scadenza — “La chiave è valida fino a questa data inclusa (smette di autenticare alla fine di quel giorno).”
3. Autorizzazioni — selezioni solo ciò di cui ha bisogno questa integrazione. Ne serve almeno una: “Selezioni almeno un’autorizzazione — la chiave può fare solo ciò che è selezionato.”
4. Crea chiave.

La chiave viene mostrata una sola volta

Copi e conservi questa chiave adesso: è l’unica volta che viene mostrata e non viene salvata da nessuna parte. Se la perde, usi «Ruota chiave» per generarne un’altra con le stesse autorizzazioni.

Non c’è modo di recuperarla in seguito. Accanto a Copia c’è Copia come variabile d’ambiente, che copia ASSINAJA_API_KEY= seguito dalla chiave, pronta da incollare in un file di configurazione. La finestra si chiude solo dopo aver spuntato Ho salvato la chiave in un luogo sicuro.

Autorizzazioni

Autorizzazione	Che cosa consente
Modelli — consultazione	Elencare e consultare modelli, inclusi firmatari e campi da compilare.
Documenti — consultazione	Elencare documenti, seguire l’avanzamento delle firme e scaricare file e report.
Documenti — link di firma	Ottenere i link di firma dei firmatari in attesa. Chi ha il link firma a nome del firmatario — è una credenziale, non una consultazione.
Documenti — creazione	Creare documenti a partire da modelli, da DOCX (MailMerge) o da un proprio PDF.
Documenti — pubblicazione	Pubblicare bozze — invia email ai firmatari ed è irreversibile.
Documenti — archiviazione/eliminazione	Archiviare ed eliminare documenti.
Organizzazione — consultazione	Vedere i dati dell’organizzazione, il piano attivo e le funzionalità disponibili.
Analytics — consultazione	Leggere le metriche aggregate dell’organizzazione: utilizzo, funnel di firma e adozione. Mai per singola persona. Funziona solo se anche Impostazioni → Policy → Accesso IA agli analytics lo consente.
Webhook — segreto di firma	Leggere e ruotare il segreto con cui firmiamo i webhook che inviamo, perché il sistema di destinazione possa convalidare l’header X-AssinaJa-Signature. Da concedere solo a chi integra i webhook: con questo segreto è possibile firmare eventi.
Catalogo di modelli	Solo nel piano Enterprise — veda sotto.

Pubblicare è l’operazione pericolosa

Documenti — pubblicazione invia email ai firmatari ed è irreversibile. Creare e pubblicare sono autorizzazioni volutamente separate, perché un’integrazione possa preparare bozze da far rivedere a una persona, senza mai poterle inviare. La conceda solo quando il sistema deve davvero inviare da solo.

Per un assistente IA, inizi senza l’autorizzazione a pubblicare

In un primo collegamento tramite MCP, selezioni Modelli — consultazione, Documenti — consultazione e Documenti — creazione, e lasci fuori Documenti — pubblicazione. L’assistente prepara tutto e lascia il documento in bozza; l’invio resta un atto suo, nell’applicazione. Dopo aver visto come si comporta, aggiunga l’autorizzazione a pubblicare, se vuole.

Documenti — consultazione non dà i link di firma: questi hanno una propria autorizzazione, Documenti — link di firma, perché chi ha un link firma al posto del firmatario. La conceda solo a un’integrazione che debba davvero consegnare i link.

Analytics — consultazione richiede anche il criterio dell’organizzazione — veda Accesso IA agli analytics.

L’autorizzazione al catalogo di modelli

Catalogo di modelli — servire altre organizzazioni è diversa dalle altre:

Consente ad altre organizzazioni di generare documenti dal catalogo di modelli di questa organizzazione (header X-Api-Key-TemplateCatalog). Non concede nessun altro accesso.

Usa un proprio header e non concede altro. È Disponibile solo nel piano Enterprise.

Una chiave con questa autorizzazione viene condivisa con altre organizzazioni, quindi non può avere anche alcuna autorizzazione Documenti: la piattaforma si rifiuta di salvarla così. Per il catalogo, usi una chiave separata.

Modelli tramite l’API pubblica: due regole

Sono regole dell’API pubblica, e valgono per qualsiasi chiave che consulti modelli:

• Il piano che conta è quello di chi serve il modello, non quello di chi chiama. Se l’organizzazione proprietaria del catalogo non ha i Modelli attivi, i cinque endpoint che usano i modelli rispondono 423 FEATURE_TEMPLATES_NOT_ENABLED.
• Per l’API le bozze non esistono. Non compaiono nell’elenco, e chiedere il dettaglio di una restituisce 404. Pubblichi il modello prima di integrarlo.

Gestire le chiavi

L’elenco mostra Nome, Chiave, Autorizzazioni, Scadenza, Stato, Creata e Ultimo utilizzo — quest’ultima indica Mai per una chiave che non ha mai effettuato un’autenticazione. Questa colonna è il modo più rapido per individuare una chiave che nessuno usa.

Azione	Effetto
Modifica	Cambiare il nome, la scadenza o le autorizzazioni
Ruota chiave	Generare un nuovo segreto per la stessa integrazione — veda sotto
Sospendi	“Quando è sospesa, la chiave non autentica finché non viene riattivata.”
Attiva	Riattivare una chiave sospesa
Elimina	Definitivo

Lo Stato di una chiave è Attiva, Sospesa o Scaduta.

Ruotare una chiave

Quando perde una chiave, o sospetta che sia stata esposta, non deve eliminarla e riconfigurare l’integrazione da zero. Ruota chiave apre Ruotare la chiave — “Viene generata una nuova chiave per questa integrazione. Nome, autorizzazioni, validità e assistenti IA collegati restano invariati; cambia solo il segreto.” — e chiede quando La chiave attuale smette di funzionare:

Opzione	Quando usarla
Subito — da usare se la chiave potrebbe essere stata esposta	“L’integrazione che usa la chiave attuale non riuscirà più ad autenticarsi dal momento della rotazione.”
Tra 1 ora — il tempo di sostituirla nel sistema che la usa	L’opzione predefinita: le due chiavi funzionano per un’ora.
Tra 24 ore	Lo stesso, con un giorno di margine.

La nuova chiave viene mostrata una sola volta, come alla creazione — Chiave ruotata, con “La chiave precedente continua a funzionare fino al {data}. La sostituisca entro quella data nel sistema che la usa.” oppure, se ha scelto subito, “La chiave precedente non funziona più.” Nell’elenco, la chiave mostra Ruotata il {data} e, finché dura la sovrapposizione, “La precedente funziona fino al {data}”.

Una chiave Scaduta non si ruota — “Scaduta: crei una nuova chiave invece di ruotarla.”

Sospenda prima di eliminare

Sospendere è reversibile; eliminare no — “è irreversibile — l’integrazione che la usa non riuscirà più ad autenticarsi da subito.” Se sospetta che una chiave sia compromessa o inutilizzata, la sospenda e veda che cosa smette di funzionare. Può sempre riattivarla.

Essere avvisati quando succede qualcosa

Perché il suo sistema venga avvisato quando succede qualcosa a un documento, invece di continuare a chiedere, veda Ricevere webhook.

Veda anche

• Ricevere webhook
• Ruoli e permessi — le chiavi API e i webhook sono riservati al Proprietario; Integrazioni e Archiviazione, al Proprietario e all’Amministratore
• Configurare i criteri dell’organizzazione