Âmbitos e permissões da API do Drive

Os âmbitos do Drive determinam exatamente o que um token de API ou agente MCP pode fazer com o TrekMail Drive. Um bom token é restrito: tem o menor conjunto de âmbitos necessário para uma tarefa, um nome claro e uma data de validade.

A API do Drive tem 11 âmbitos que abrangem o Drive da conta, o Drive da caixa de correio, ligações de partilha, eliminação permanente, estado do complemento do Drive e palavras-passe de dispositivos de sincronização. Estes âmbitos pertencem a tokens de operações (tm_live_...). Os tokens de mensagens (tm_msg_...) continuam a destinar-se a operações de correio eletrónico.

Referência dos âmbitos

Leitura, escrita, partilha e eliminação

O Drive separa as tarefas comuns em quatro níveis de permissão:

• Leitura permite listar espaços, explorar pastas, verificar metadados, ver o lixo e pedir URLs de transferência.
• Escrita permite carregar, criar pastas, mudar o nome, mover, enviar para o lixo e restaurar.
• Partilha permite criar, listar e revogar ligações públicas de partilha.
• Eliminação permite apagar permanentemente itens do lixo ou esvaziá-lo.

Não conceda a eliminação a um assistente de uso geral. Para limpeza automatizada, crie um token separado com o nome dessa tarefa, mantenha-o desativado no MCP até ser necessário e reveja o registo de auditoria após cada execução.

Acesso por plano e complemento

O acesso à API do Drive está disponível quando a conta tem direito ao Drive através de um plano pago ou de um complemento de armazenamento do Drive ativo. Uma conta gratuita com complemento ativo pode usar âmbitos do Drive para automatizar o armazenamento, tal como os âmbitos do Verificador de e-mail estão disponíveis independentemente do acesso total à API de infraestrutura.

Se um complemento do Drive for cancelado e entrar no período de tolerância, o acesso de leitura poderá continuar disponível para rever e exportar ficheiros. A escrita, a partilha e a eliminação poderão ficar restringidas até a conta regressar a um estado de armazenamento ativo.

Drive da conta e Drive da caixa de correio

Os âmbitos do Drive da conta e da caixa estão intencionalmente separados. Um agente de faturação ou operações poderá precisar apenas do Drive da conta. Um assistente de caixa poderá precisar do Drive de uma única caixa e de mais nada.

Utilize limites de caixa ao criar um token para automatização. Um token restrito só vê espaços de caixas permitidas. Os pedidos para outras caixas devolvem uma resposta semelhante a «não encontrado», evitando revelar a estrutura da conta a uma integração de âmbito reduzido.

O âmbito do complemento do Drive é só de leitura

drive:addon:read permite consultar estado, preços e pré-visualização de cancelamento do complemento. Não permite comprar armazenamento, alterar capacidade, cancelar uma subscrição nem iniciar um pagamento.

Este limite é intencional. As alterações de faturação do armazenamento permanecem no painel, onde uma pessoa pode rever capacidade, preço, moeda, período de faturação e confirmação do pagamento. Não existe o âmbito drive:addon:write.

Palavras-passe de dispositivos de sincronização

drive:devices:read e drive:devices:write gerem as palavras-passe separadas utilizadas por aplicações de sincronização WebDAV. Não são o token de API. Uma palavra-passe criada é mostrada uma vez, por isso guarde-a de imediato na aplicação ou num gestor de palavras-passe. Quando possível, separe a gestão de dispositivos de um token geral de automatização de ficheiros e revogue a palavra-passe quando o computador ou a aplicação já não se deva ligar.

As respostas de listagem, criação e substituição incluem server_url. Utilize o endereço devolvido em vez de criar /dav: contas com zona de correio White Label totalmente aprovisionada recebem o nome de anfitrião DAV da marca; todas as outras recebem o nome funcional da plataforma.

Padrões de tokens recomendados

O que acontece quando falta um âmbito

Se um token não tiver o âmbito do Drive necessário, a API devolve um erro de permissão. Se as restrições excluírem uma caixa ou recurso, a API poderá devolver «não encontrado». Isto protege a estrutura privada da conta de integrações que não a devem conhecer.