Crea e gestisci una chiave API

Apri Profilo → Chiavi API, seleziona Crea una chiave API, assegna un nome e scegli cosa può fare. Controlla Restrizioni e scadenza prima di selezionare Genera la chiave, poi copia la chiave mentre la finestra del risultato è aperta. La chiave completa viene mostrata una sola volta.

Prima di iniziare

• Accedi all’account che l’integrazione deve usare. Le chiavi API si gestiscono nel profilo dell’account e possono anche essere limitate a uno spazio di lavoro.
• Verifica protocollo e permessi necessari allo strumento. Crea una chiave separata per ogni strumento, così potrai identificarla e revocarla indipendentemente.
• Prepara un archivio privato delle credenziali. Non inserire la chiave in un repository pubblico, uno screenshot condiviso o un messaggio all’assistenza.
• Se vuoi limitarla a uno spazio di lavoro o a una cartella, verifica di esserne membro e individua la cartella a cui l’integrazione deve accedere.

Passaggi: genera e salva una chiave

1. Trova le chiavi API. Apri Menu dell’account dall’avatar, seleziona Profilo, poi Chiavi API nella navigazione del profilo. Puoi anche aprire direttamente Chiavi API.
2. Apri il modulo. Scegli Crea una chiave API nella barra sopra l’elenco delle chiavi.
3. Indica lo scopo. In A cosa serve?, inserisci un nome riconoscibile, per esempio strumento e scopo. Il nome identifica la chiave, non è la credenziale. Può contenere al massimo 64 caratteri.
4. Scegli il permesso. In Cosa può fare?, seleziona Sola lettura, Solo caricamento o Accesso completo. Sola lettura consente di elencare e scaricare. Solo caricamento consente caricamenti e creazione di cartelle, ma non l’elenco, il download o l’eliminazione di file esistenti. Non garantisce la sola creazione: un caricamento REST con lo stesso nome può aggiungere una versione a un file esistente se il tuo accesso lo consente. Accesso completo è l’opzione più permissiva. Il modulo seleziona inizialmente Accesso completo, quindi fai una scelta esplicita.
5. Controlla le restrizioni. Apri Restrizioni e scadenza. Segui le opzioni sotto per limitare la chiave a protocolli, spazio di lavoro, indirizzi, orari e utilizzo previsti. Un nuovo modulo senza restrizioni presenta anche Intero account, Tutti i protocolli e Non scade mai.
6. Leggi il riepilogo. Confronta la descrizione in fondo al modulo con lo scopo dello strumento. Verifica che ambito di accesso, permesso e scadenza siano quelli voluti.
7. Genera la credenziale. Scegli Genera la chiave. Se la creazione riesce, una finestra con il nome della chiave e is ready nel titolo mostra la chiave completa.
8. Salvala prima di uscire. Usa Copia accanto alla chiave e conservala privatamente, poi inseriscila nelle impostazioni delle credenziali dello strumento. Scegli Fatto solo dopo averla salvata. Uscendo dalla finestra non potrai più vedere la chiave completa.

Scegli restrizioni adatte allo strumento

Il modulo espanso raggruppa le opzioni per domanda:

• Quale ambito di accesso ha? In Protocolli, scegli Tutti i protocolli o Solo quelli che scelgo. Se scegli la seconda opzione, spunta almeno uno tra API REST, WebDAV, SFTP o Gateway S3. Se non spunti alcun protocollo, il modulo omette la restrizione e la chiave resta abilitata su tutti i protocolli. Prima di generarla seleziona il protocollo effettivamente necessario. In Spazio di lavoro, scegli uno spazio di lavoro per sostituire Intero account con uno spazio di lavoro. Dopo averlo scelto, Scegli cartella… può limitare l’accesso a una cartella e alle sue sottocartelle; il selettore usa Seleziona cartella per confermare.
• Da dove può essere usata? Aggiungi indirizzi o intervalli CIDR separati da virgole in Intervalli IP consentiti, oppure attiva Solo in una fascia oraria settimanale e scegli fuso orario, giorni e orari Da e A.
• Quanto può usare? Inserisci facoltativamente Richieste al minuto, Download al giorno (GB), Peso massimo del file (MB) o Trasferimenti simultanei. I campi vuoti non aggiungono limiti specifici alla chiave e non annullano quelli del piano o del servizio applicabili.
• Quando deve smettere di funzionare? Scegli Non scade mai, Scade tra 30 giorni o Scade tra 90 giorni.

Prima di salvare considera due vincoli: una chiave limitata a una cartella può essere usata solo su WebDAV o sul gateway S3 e l’aggiunta di un elenco di IP consentiti impedisce a SFTP di funzionare con quella chiave. Controlla le spiegazioni del modulo quando combini queste opzioni.

Risultato previsto

La nuova chiave appare nell’elenco Chiavi API. La sua riga mostra Permesso, Protocolli, Ambito di accesso e Ultimo utilizzo, con la scadenza se applicabile. L’elenco mostra un identificatore parziale anziché la credenziale completa.

Configura lo strumento con il protocollo scelto e prova l’operazione prevista. Una chiave con permesso, ambito di accesso o condizioni errati può essere creata, ma la richiesta può essere rifiutata.

Esamina, sostituisci o revoca una chiave

Usa Cerca nome o prefisso e il filtro dei permessi per trovare una chiave. Espandi la riga con il controllo alla sua estremità per vedere Configurazione, Vincoli e Azioni.

Le chiavi non possono essere modificate dopo la creazione. Duplica le impostazioni apre un modulo per una nuova chiave con alcune impostazioni della chiave già compilate. Controlla attentamente la nuova chiave: la scadenza inizia da Non scade mai e i limiti di utilizzo sono vuoti. Imposta di nuovo scadenza e limiti desiderati prima di generarla. Genera e salva la nuova chiave, aggiorna lo strumento e poi revoca la vecchia credenziale quando opportuno.

Per revocare una chiave, espandi la riga, seleziona Revoca, controlla la finestra di conferma e seleziona ancora Revoca. L’azione è irreversibile. Le richieste degli strumenti che usano ancora quella chiave saranno rifiutate. Puoi anche selezionare le caselle di più righe e usare Revoca per revocare le chiavi selezionate.

Credenziali S3

Un token API e una coppia di credenziali S3 sono credenziali diverse. Se la chiave consente Gateway S3, espandi la riga e seleziona Attiva accanto a Credenziali S3. La finestra risultante fornisce ID chiave di accesso, Chiave di accesso segreta, Indirizzo del servizio e Regione per un client compatibile con S3.

Salva il segreto prima di selezionare Fatto. Attive · mostra consente di rivedere in seguito gli altri dettagli S3, ma non il segreto. Una chiave scaduta non può abilitare l’accesso S3 e una chiave che esclude S3 mostra Non consentito.

Limiti dell’account e messaggi di errore

Il piano gratuito consente 3 chiavi API per utente nell’intero account; gli altri piani hanno comunque un massimo di 20 in totale. Il conteggio include le chiavi scadute finché non le revochi. Una restrizione allo spazio di lavoro modifica l’ambito di accesso, non il conteggio. Puoi generare chiavi con il piano gratuito. Per specificare uno spazio di lavoro devi esserne membro.

Risposta di creazione	Soluzione
Name is required	Compila A cosa serve? con un nome non vuoto.
Name must be 64 characters or less	Accorcia il nome; modificarlo non cambia la sicurezza del token.
Maximum of 20 API keys reached	Revoca una credenziale inutilizzata prima di generarne un’altra.
The free plan allows 3 API keys. Delete one or upgrade for more.	Controlla l’intero elenco, incluse le chiavi scadute.
Not a member of that workspace	Scegli uno spazio di lavoro di cui sei membro; creare una chiave non ti rende membro.
Folder not found in that workspace	Riapri il selettore cartelle nello spazio di lavoro scelto e scegli una cartella attiva.
Invalid IP/CIDR entry: "…"	Correggi l’indirizzo o la sottorete indicati invece di eliminare il limite di accesso previsto.

Il limite di 20 chiavi viene controllato prima di quello del piano gratuito. Una chiave generata può comunque essere rifiutata quando la usi: protocollo, condizioni di indirizzo e orario, vincolo alla cartella, ambito dell’operazione e vincolo allo spazio di lavoro vengono verificati prima di conteggiare la richiesta. Il ruolo resta un ulteriore limite, anche con Accesso completo.

Unità e scadenza che influiscono sull’integrazione

Download al giorno (GB) e Peso massimo del file (MB) usano unità in base 1024: 1 GB equivale a 1.073.741.824 byte e 1 MB a 1.048.576 byte. I limiti di richieste e trasferimenti simultanei indicano un numero. I limiti salvati richiedono interi positivi; zero non significa utilizzo illimitato. Lascia vuoto un campo facoltativo per non aggiungere un limite specifico alla chiave; restano validi i vincoli applicabili del piano e dello spazio di lavoro.

Scade tra 30 giorni e Scade tra 90 giorni si misurano dalla creazione, non dal primo uso. Non scade mai non imposta una scadenza programmata. La credenziale è utilizzabile quando la creazione riesce, quindi salvala e configurala prima di abilitare un processo. Considera la scadenza mostrata come termine di accesso; non contare sulla cache di autenticazione già attiva per prolungarlo.

Per REST prevale il più restrittivo tra limiti espliciti della chiave e limiti applicabili del piano per numero di richieste, trasferimenti simultanei e byte scaricati. WebDAV, S3 e SFTP non applicano i limiti del piano al numero di richieste o ai trasferimenti simultanei, ma i limiti espliciti della credenziale restano validi e quelli sui byte scaricati valgono per ogni protocollo. Quando richiedi un URL di download firmato, la dimensione del file viene conteggiata al rilascio dell’URL, anche se non viene mai usato. I contatori giornalieri si azzerano a mezzanotte UTC; la finestra settimanale degli orari attivi usa invece il fuso orario scelto.

Usa e verifica il token

Per un client REST, invia Authorization: Bearer seguito dal token dos_ completo. Una credenziale Sola lettura può eseguire questa richiesta innocua; una credenziale Solo caricamento non può elencare gli spazi di lavoro:

# DOSYA_API_KEY must already be supplied privately by your secret store.
curl --fail-with-body --silent --show-error \
  'https://api.dosya.dev/api/workspaces' \
  -H "Authorization: Bearer $DOSYA_API_KEY"

Verifica che la risposta sia HTTP 200 e che l’array workspaces corrisponda all’account previsto. Un vincolo limita l’array allo spazio di lavoro selezionato. Per una credenziale di caricamento, verifica invece con un piccolo caricamento e l’ID file restituito; lo stato della sessione è consentito, ma l’elenco ordinario dei file no.

Un 401 con Invalid or expired API key indica un token non valido, scaduto o revocato. Un 403 che nomina api surface indica che REST API è esclusa. Un messaggio che nomina ambito della credenziale, metodo e percorso indica che serve un permesso diverso; ampliare l’accesso allo spazio di lavoro non risolve il problema. Un 429 fornisce Retry-After in secondi. Un 503 temporaneo durante l’autenticazione chiede di riprovare dopo cinque secondi e non significa che la chiave sia persa.

L’amministrazione delle chiavi API richiede una sessione autenticata dell’account: un token bearer non può creare, elencare o revocare altre chiavi tramite gli endpoint del profilo. Questo protegge le altre credenziali anche quando la chiave presentata ha Accesso completo.

Limiti e risoluzione dei problemi

La chiave API completa e il segreto S3 non sono recuperabili in seguito. Se perdi uno dei due, crea nuove credenziali e revoca la vecchia chiave se necessario. Copiare un identificatore parziale dall’elenco non autentica uno strumento.

Se Genera la chiave non riesce, controlla il nome e il messaggio di errore. Se hai raggiunto il limite di chiavi dell’account, rimuovi una chiave non necessaria o controlla il piano prima di crearne un’altra. Le chiavi scadute restano nell’elenco: considerale nel totale.

Se le richieste di uno strumento vengono rifiutate, controlla Permesso, Protocolli, Ambito di accesso, scadenza, elenco di IP consentiti e orari attivi. Una chiave limitata a una cartella non funziona su REST API o SFTP. Un client SFTP non funziona con una chiave limitata per IP. Non ampliare l’accesso per risolvere questi errori prima di verificare il requisito effettivo.

Usa l’assistenza privata per un problema persistente con le credenziali. Condividi nome della chiave, protocollo scelto e messaggio di errore; ometti chiave completa, intestazioni di autorizzazione, segreto S3 e comandi generati per le credenziali.

Domande frequenti

Posso rivedere la chiave completa dopo aver selezionato Done?

No. Il token completo viene mostrato solo alla creazione. Se non l’hai salvato, crea una nuova chiave, aggiorna l’integrazione e revoca la vecchia chiave inutilizzata.

Duplicate settings conserva tutte le restrizioni?

No. Controlla il modulo della nuova chiave: i limiti di utilizzo sono vuoti e la scadenza inizia da Non scade mai. Imposta esplicitamente queste opzioni prima di generarla.

Revocare le sessioni revoca anche le chiavi API?

Le chiavi API sono gestite separatamente. Revoca la chiave in questa pagina quando un’integrazione deve smettere di autenticarsi. Usa Profilo → Sessioni per esaminare browser e app che hanno effettuato l’accesso.

Guide correlate

• Esamina le sessioni attive
• Guarda il tutorial sulle chiavi API
• Guarda il tutorial su WebDAV