Ámbitos y permisos de la API de Drive

Los ámbitos de Drive determinan exactamente qué puede hacer un token de API o agente MCP con TrekMail Drive. Un buen token es limitado: tiene el conjunto mínimo de ámbitos necesarios para una tarea, un nombre claro y una fecha de caducidad.

La API de Drive tiene 11 ámbitos que abarcan Drive de la cuenta, Drive del buzón, enlaces compartidos, eliminación permanente, estado del complemento de Drive y contraseñas de dispositivos de sincronización. Estos ámbitos pertenecen a los tokens de operaciones (tm_live_...). Los tokens de mensajes (tm_msg_...) siguen siendo para operaciones de correo electrónico.

Referencia de ámbitos

Lectura, escritura, uso compartido y purga

Drive divide las tareas habituales en cuatro niveles de permisos:

• Lectura permite enumerar espacios, explorar carpetas, consultar metadatos, ver la papelera y solicitar URL de descarga.
• Escritura permite cargar, crear carpetas, renombrar, mover, enviar a la papelera y restaurar.
• Uso compartido permite crear, enumerar y revocar enlaces públicos compartidos.
• Purga permite eliminar permanentemente elementos de la papelera o vaciarla.

No concedas el permiso de purga a un asistente de uso general. Si necesitas una limpieza automatizada, crea un token independiente cuyo nombre describa esa tarea, mantenlo desactivado en MCP hasta que se necesite y revisa el registro de auditoría después de cada ejecución.

Acceso por plan y complemento

El acceso a la API de Drive está disponible cuando la cuenta tiene derecho a Drive mediante un plan de pago o un complemento de almacenamiento de Drive activo. Una cuenta gratuita con un complemento activo puede utilizar ámbitos de Drive para automatizar el almacenamiento, de forma similar a los ámbitos del Verificador de correo, disponibles independientemente del acceso completo a la API de infraestructura.

Si se cancela un complemento de Drive y comienza su periodo de gracia, el acceso de lectura puede seguir disponible para revisar y exportar archivos. El acceso de escritura, uso compartido y purga puede quedar restringido hasta que la cuenta vuelva a tener un estado de almacenamiento activo.

Drive de la cuenta frente a Drive del buzón

Los ámbitos de Drive de la cuenta y del buzón están separados intencionadamente. Un agente de facturación u operaciones puede necesitar solo Drive de la cuenta. Un asistente de buzón puede necesitar acceso a Drive de un único buzón y nada más.

Utiliza límites de buzón al crear un token para automatizar buzones. Un token restringido solo puede ver los espacios de los buzones permitidos. Las solicitudes de otros buzones devuelven una respuesta similar a «no encontrado», lo que evita revelar la estructura de la cuenta a una integración con permisos limitados.

El ámbito del complemento de Drive es de solo lectura

drive:addon:read permite a un agente consultar el estado, los precios y la vista previa de cancelación del complemento. No permite comprar almacenamiento, cambiar la capacidad de un complemento, cancelar una suscripción ni iniciar una acción de pago.

Este límite es deliberado. Los cambios de facturación del almacenamiento permanecen en el panel, donde una persona puede revisar la capacidad, el precio, la moneda, el periodo de facturación y la confirmación del pago. No existe el ámbito drive:addon:write.

Contraseñas de dispositivos de sincronización

drive:devices:read y drive:devices:write administran las contraseñas independientes utilizadas por aplicaciones de sincronización WebDAV. No son lo mismo que el token de API. Una contraseña de dispositivo creada se muestra una sola vez, así que guárdala en la aplicación de sincronización o en un gestor de contraseñas en ese momento. Siempre que sea posible, separa la administración de dispositivos de un token general para automatizar archivos y revoca la contraseña de un dispositivo cuando su ordenador o aplicación ya no deba conectarse.

Las respuestas para enumerar, crear y rotar dispositivos incluyen server_url. Utiliza la dirección devuelta en vez de construir /dav por tu cuenta: las cuentas con una zona de correo White Label totalmente aprovisionada reciben su nombre de host DAV de marca, mientras que las demás cuentas reciben el nombre de host operativo de la plataforma.

Patrones de tokens recomendados

Qué ocurre cuando falta un ámbito

Si un token no tiene el ámbito de Drive necesario, la API devuelve un error de permisos. Si el token tiene una restricción que excluye un buzón o recurso, la API puede devolver que no se ha encontrado. Esto protege la estructura privada de la cuenta frente a integraciones que no deben conocerla.