Ambiti e autorizzazioni dell’API Drive

Gli ambiti Drive stabiliscono esattamente cosa può fare un token API o un agente MCP con TrekMail Drive. Un buon token è ristretto: ha solo gli ambiti necessari per un’attività, un nome chiaro e una data di scadenza.

L’API Drive ha 11 ambiti per Drive dell’account, Drive delle caselle, link di condivisione, eliminazione permanente, stato dell’add-on Drive e password dei dispositivi di sincronizzazione. Questi ambiti appartengono ai token operativi (tm_live_...). I token dei messaggi (tm_msg_...) restano destinati alle operazioni e-mail.

Riferimento degli ambiti

Lettura, scrittura, condivisione ed eliminazione

Drive divide le attività comuni in quattro livelli:

• Lettura elenca spazi, esplora cartelle, esamina metadati, mostra il cestino e richiede URL di download.
• Scrittura carica file, crea cartelle, rinomina, sposta, cestina e ripristina.
• Condivisione crea, elenca e revoca link pubblici.
• Eliminazione cancella definitivamente elementi cestinati o svuota il cestino.

Non concedere l’eliminazione a un assistente generico. Per la pulizia automatizzata, crea un token separato che riporti il nome dell’attività, lascialo disabilitato in MCP finché non serve e controlla il registro di audit dopo ogni esecuzione.

Accesso tramite piano e add-on

L’API Drive è disponibile quando l’account dispone di Drive tramite un piano a pagamento o un add-on di archiviazione Drive attivo. Un account gratuito con add-on attivo può usare gli ambiti Drive per automatizzare lo spazio, come gli ambiti del Verificatore e-mail sono disponibili indipendentemente dall’accesso completo all’API dell’infrastruttura.

Se un add-on viene annullato ed entra nel periodo di tolleranza, la lettura può restare disponibile per esaminare ed esportare i file. Scrittura, condivisione ed eliminazione possono essere limitate finché l’account non torna a uno stato di archiviazione attivo.

Drive dell’account e Drive della casella

Gli ambiti dell’account e quelli delle caselle sono separati intenzionalmente. Un agente di fatturazione può richiedere solo Drive dell’account; un assistente può richiedere il Drive di una sola casella.

Usa i vincoli sulle caselle quando crei un token di automazione. Un token vincolato vede solo gli spazi consentiti. Le richieste per altre caselle restituiscono una risposta simile a «non trovato», evitando di rivelare la struttura dell’account.

L’ambito dell’add-on Drive è di sola lettura

drive:addon:read legge stato, prezzi e anteprima di annullamento. Non può acquistare spazio, modificare la capacità, annullare un abbonamento o avviare un pagamento.

Questo limite è intenzionale. Le modifiche di fatturazione restano nella dashboard, dove una persona controlla capacità, prezzo, valuta, periodo e conferma del pagamento. Non esiste un ambito drive:addon:write.

Password dei dispositivi di sincronizzazione

drive:devices:read e drive:devices:write gestiscono le password separate usate dalle app WebDAV. Non coincidono con il token API. Una password creata è mostrata una volta: salvala subito nell’app o in un gestore. Se possibile, separa la gestione dei dispositivi dall’automazione dei file e revoca la password quando il computer o l’app non deve più collegarsi.

Le risposte di elenco, creazione e rotazione includono server_url. Usa l’indirizzo restituito invece di comporre /dav: gli account con zona e-mail White Label completa ricevono il proprio hostname DAV, gli altri quello operativo della piattaforma.

Modelli di token consigliati

Cosa accade se manca un ambito

Se manca l’ambito Drive richiesto, l’API restituisce un errore di autorizzazione. Se il token è escluso da una casella o risorsa, può restituire «non trovato». Ciò protegge la struttura privata dell’account.