Drive API 权限范围与许可参考指南
介绍 TrekMail Drive 的 11 个 API 权限范围、方案与附加服务访问、邮箱限制、删除权限及安全令牌设计。
文章详情
类型、难度、套餐及最近更新信息。
▼
文章详情
类型、难度、套餐及最近更新信息。
- 类型
- 参考资料
- 难度
- 中级
- 套餐
- Starter · Pro · Agency · + Drive Add-on
- 最近更新
- 2026年9月10日
Drive 权限范围准确决定 API 令牌或 MCP 代理可以对 TrekMail Drive 执行的操作。良好的令牌权限应尽可能小，只包含一项任务所需的最少权限范围，并有明确名称和到期日期。
Drive API 有 11 个权限范围，涵盖账户 Drive、邮箱 Drive、共享链接、永久删除、Drive 附加服务状态和同步设备密码。这些范围属于操作令牌 (tm_live_...)。消息令牌 (tm_msg_...) 仍用于电子邮件操作。
权限范围参考
| 权限范围 | 用途 | 说明 |
|---|---|---|
drive:account:read |
列出账户 Drive 空间、文件夹、文件、回收站、用量和下载链接 | 报告和搜索代理的安全默认值 |
drive:account:write |
创建文件夹、上传、重命名、移动、移入回收站和恢复 | 可更改文件但不能永久删除 |
drive:account:share |
创建、列出和撤销账户 Drive 文件的公共共享链接 | 原始共享令牌仅在创建时返回 |
drive:account:purge |
永久清除回收站项目并清空回收站 | 高风险，仅授予可信维护代理 |
drive:mailbox:read |
浏览令牌允许的邮箱 Drive 空间 | 可通过邮箱限制缩小范围 |
drive:mailbox:write |
在允许的邮箱 Drive 空间上传和管理文件 | 会更改邮箱所有的 Drive 数据 |
drive:mailbox:share |
创建、列出和撤销允许的邮箱文件公共链接 | 应设置明确到期时间和下载限制 |
drive:mailbox:purge |
永久清除邮箱 Drive 中已删除的文件和文件夹 | 高风险，应与日常自动化分开 |
drive:addon:read |
读取 Drive 附加服务状态、价格和取消预览 | 只读，不更改订阅 |
drive:devices:read |
列出 Drive 同步设备密码 | 显示标签、范围、上次使用和到期时间，绝不显示明文密码 |
drive:devices:write |
创建、轮换和撤销同步设备密码 | 只能在调用者自身 Drive 权限内创建密码 |
读取、写入、共享与彻底清除
Drive 将常见任务分为四个权限级别：
- 读取可列出空间、浏览文件夹、检查元数据、查看回收站和请求下载 URL。
- 写入可上传、创建文件夹、重命名、移动、移入回收站和恢复。
- 共享可创建、列出和撤销公共共享链接。
- 彻底清除可永久删除回收站项目或清空回收站。
不要向通用助手授予彻底清除权限。自动清理应使用以该任务命名的独立令牌，在需要前保持 MCP 禁用，并在每次运行后检查审计日志。
方案和附加服务访问
账户通过付费方案或有效的 Drive 存储附加服务获得 Drive 权益后，即可访问 Drive API。拥有有效附加服务的免费账户也可使用 Drive 范围自动管理存储，类似于电子邮件验证器范围无需完整基础设施 API 访问即可使用。
如果附加服务取消并进入宽限期，读取权限可能保留，以便检查和导出文件。写入、共享和彻底清除权限可能受限，直到恢复有效存储状态。
账户 Drive 与邮箱 Drive
账户和邮箱 Drive 权限范围有意分开。计费或运营代理可能只需账户 Drive，而邮箱助手可能只需一个邮箱 Drive。
为邮箱自动化创建令牌时应使用邮箱限制。受限令牌只能看到允许的空间。对其他邮箱的请求会返回类似“未找到”的响应，避免向权限有限的集成泄露账户结构。
Drive 附加服务范围只读
drive:addon:read 可读取附加服务状态、价格和取消预览，不能购买存储、调整容量、取消订阅或发起付款。
这一边界是有意设置的。存储计费更改应留在仪表板中，由用户检查容量、价格、币种、周期和付款确认。不存在 drive:addon:write 范围。
同步设备密码
drive:devices:read 和 drive:devices:write 管理 WebDAV 同步应用使用的独立密码，与 API 令牌不同。新密码仅显示一次，请立即保存到同步应用或密码管理器。尽可能将设备管理与通用文件自动化令牌分开，并在设备不应再连接时撤销密码。
设备列表、创建和轮换响应包含 server_url。请使用返回的地址，不要自行拼接 /dav：拥有完整 White Label 邮件区域的账户会收到品牌 DAV 主机名，其他账户会收到可用的平台主机名。
推荐令牌模式
| 工作流 | 推荐范围 | 避免 |
|---|---|---|
| 报告代理 | drive:account:read，可加 drive:mailbox:read |
写入/共享/彻底清除 |
| 上传自动化 | drive:account:read、drive:account:write |
彻底清除 |
| 客户交付链接 | drive:account:read、drive:account:share |
彻底清除，除非单独清理 |
| 邮箱助手 | drive:mailbox:read，可加 drive:mailbox:write，限一个邮箱 |
全账户范围 |
| 清理任务 | 读取/写入及所需的精确清除范围 | 宽泛无限制令牌 |
| 存储监控 | drive:addon:read、drive:account:read |
API 不提供的计费写入 |
| 同步设备管理 | drive:devices:read、drive:devices:write 及所需文件范围 |
带无关写入范围的全账户令牌 |
缺少权限范围时
如果令牌缺少所需 Drive 范围，API 会返回权限错误。如果令牌限制排除了邮箱或资源，API 可能返回未找到。这可保护私密账户结构。
相关文章
跳转到延续此工作流的邻近指南。