Autentica la CLI dosya in sicurezza

La CLI dosya si autentica con una chiave API dos_. Usa la richiesta interattiva nascosta su un terminale personale, passa la chiave tramite input standard a uno script di configurazione oppure fornisci DOSYA_API_KEY a un ambiente di automazione. Evita di inserire un segreto riutilizzabile subito dopo --key: la cronologia della shell e l’elenco dei processi potrebbero esporlo.

Crea una chiave per questa installazione CLI

Apri Profilo → Chiavi API, scegli Crea una chiave API e assegna un nome per questo computer o processo automatizzato. Scegli il permesso minimo necessario ai comandi previsti:

• Sola lettura permette di elencare e scaricare, ma non di caricare, spostare o eliminare.
• Solo caricamento permette di aggiungere file, ma non di elencare o scaricare i file salvati.
• Accesso completo supporta lettura e modifica dei contenuti, nei limiti dei permessi del ruolo nello spazio di lavoro.

In Protocolli, includi API REST perché la CLI usa gli endpoint REST. Se adatti al processo, aggiungi un vincolo allo spazio di lavoro, intervalli IP, orari attivi, limiti di utilizzo o una scadenza. Salva il token completo mostrato una sola volta: in seguito la tabella delle chiavi mostra solo un prefisso.

Procedura

Esegui il comando interattivo e incolla la chiave quando compare la richiesta nascosta:

dosya auth login
dosya whoami

Se l’accesso riesce viene mostrato Authenticated as NAME (EMAIL). Poi dosya whoami mostra nome account, email, ID utente e numero di spazi di lavoro; dosya whoami --json restituisce l’oggetto account per uno script.

La CLI salva il token e l’indirizzo base API in ~/.dosya/config.json, oppure in $XDG_CONFIG_HOME/dosya/config.json se XDG_CONFIG_HOME è impostato. Su sistemi Unix la directory è creata con modalità 0700 e il file con 0600. La chiave è in chiaro nel file protetto. Se i permessi ripristinati consentono la lettura al gruppo o ad altri utenti, la CLI avvisa e propone il comando correttivo chmod 600.

Autentica uno script senza esporre gli argomenti di argv

Passa la chiave tramite stdin:

printf '%s\n' "$MY_KEY" | dosya auth login --key -
dosya whoami --json

Una pipe vuota produce No API key on stdin. Un’esecuzione non interattiva senza --key - o DOSYA_API_KEY produce Cannot prompt for API key in non-interactive mode. Un valore che non inizia con dos_ viene rifiutato prima della richiesta di rete.

Per CI o un contenitore di breve durata, inserisci la chiave come segreto d’ambiente senza scriverla su disco:

export DOSYA_API_KEY="$MY_KEY"
dosya whoami --json

La precedenza delle credenziali è --key, poi DOSYA_API_KEY, quindi la configurazione salvata. Per l’indirizzo API la precedenza è DOSYA_API_BASE, poi il file di configurazione e infine https://api.dosya.dev. Controlla quale origine prevale prima di cercare la causa di un account o ambiente inatteso.

Risolvi i problemi comuni di autenticazione

Output CLI	Cosa fare
Authentication failed: invalid API key.	Copia il token completo mostrato una sola volta oppure creane uno sostitutivo se il valore originale non è più disponibile.
Not authenticated. Run: dosya auth login	Fornisci DOSYA_API_KEY o completa un accesso salvato.
Authentication failed. Run 'dosya auth login' to re-authenticate.	Il server ha restituito 401; controlla scadenza o revoca e sostituisci la credenziale.
Permission denied. You don't have access to this resource (403).	La chiave è ancora valida, ma ambito, protocollo, condizioni di origine, vincolo allo spazio di lavoro o ruolo corrente hanno negato l’operazione.
Una chiave funziona in locale ma non in CI	Confronta la chiave inserita, DOSYA_API_BASE, l’elenco di IP consentiti, il fuso orario degli orari attivi e l’appartenenza allo spazio di lavoro selezionato.

Il codice di uscita 3 indica un errore di autenticazione, 5 una credenziale valida a cui è stato negato l’accesso, 4 un errore di rete e 2 un uso non valido della CLI. L’automazione non deve rispondere al codice 5 ripetendo l’accesso.

Esci o revoca la chiave

dosya auth logout rimuove solo il file di configurazione locale. La chiave API continua a funzionare altrove finché non scade o viene revocata:

dosya auth logout

Per eliminare la chiave salvata sul server e poi cancellare il file locale, esegui:

dosya auth logout --revoke

La revoca sul server è irreversibile. Elimina la chiave e richiede l’invalidazione della cache. L’autenticazione memorizzata può restare valida finché le cache non vengono svuotate o scadono; ferma i vecchi client e verifica che l’accesso venga rifiutato prima di considerarlo chiuso. Se la revoca non riesce, la CLI conserva la credenziale locale per riprovare. Un 401 indica che la chiave salvata non è già più valida, quindi la CLI la cancella in sicurezza. Il logout non gestisce DOSYA_API_KEY presente solo nell’ambiente; revoca quella credenziale da Profilo → Chiavi API.

Risultato previsto

dosya whoami identifica l’account desiderato senza stampare la chiave. Conosci l’origine della credenziale e l’indirizzo del servizio; se usi un file salvato, questo è leggibile solo dal proprietario. Puoi revocare la chiave separatamente quando dismetti questa installazione della CLI.

Guide correlate

• Installare la CLI dosya
• Scegliere lo spazio di lavoro predefinito della CLI
• Scegliere i permessi della chiave API