Drive API のスコープと権限の詳細ガイド

Drive スコープは、API トークンや MCP エージェントが TrekMail Drive でできることを正確に決めます。適切なトークンは、1 つの仕事に必要な最小限のスコープ、明確な名前、有効期限だけを持ちます。

Drive API には、アカウント Drive、メールボックス Drive、共有リンク、完全削除、Drive アドオンの状態、同期デバイスのパスワードに対応する 11 個のスコープがあります。これらは運用トークン (tm_live_...) 用です。メッセージトークン (tm_msg_...) は引き続きメール操作用です。

スコープ一覧

読み取り、書き込み、共有、完全削除

Drive は一般的な作業を 4 段階に分けます。

• 読み取りは領域やフォルダーの表示、メタデータ確認、ゴミ箱の表示、ダウンロード URL の要求ができます。
• 書き込みはアップロード、フォルダー作成、名前変更、移動、ゴミ箱への移動、復元ができます。
• 共有は公開共有リンクの作成、一覧表示、取り消しができます。
• 完全削除はゴミ箱内の項目の永久削除やゴミ箱の消去ができます。

汎用アシスタントに完全削除を与えないでください。自動清掃には、仕事の名前を付けた別トークンを作り、必要になるまで MCP で無効にし、実行後に監査ログを確認します。

プランとアドオンによるアクセス

有料プランまたは有効な Drive ストレージアドオンにより Drive の利用権がある場合、Drive API を利用できます。有効なアドオンがある無料アカウントも、メール検証スコープと同様に、完全なインフラ API とは独立して Drive スコープを利用できます。

アドオンをキャンセルして猶予期間に入っても、ファイルの確認とエクスポート用に読み取り権限が残る場合があります。書き込み、共有、完全削除は、有効なストレージ状態に戻るまで制限される場合があります。

アカウント Drive とメールボックス Drive

両者のスコープは意図的に分かれています。請求エージェントはアカウント Drive だけ、メールボックスアシスタントは 1 つのメールボックス Drive だけを必要とする場合があります。

メールボックス自動化用トークンには制限を設定します。制限されたトークンは許可された領域だけを表示します。ほかのメールボックスへの要求には「見つかりません」に相当する応答を返し、アカウント構造を隠します。

Drive アドオンのスコープは読み取り専用

drive:addon:read は状態、料金、キャンセルプレビューを読み取れますが、購入、容量変更、解約、支払いはできません。

この境界は意図的です。請求変更は、人が容量、価格、通貨、請求期間、支払い確認を確認できるダッシュボードで行います。drive:addon:write スコープはありません。

同期デバイスのパスワード

drive:devices:read と drive:devices:write は WebDAV アプリ用の別パスワードを管理します。API トークンとは異なります。作成したパスワードは一度だけ表示されるため、その場でアプリかパスワード管理ツールに保存します。可能なら一般的なファイル自動化からデバイス管理を分離し、接続不要になったら取り消してください。

一覧、作成、更新の応答には server_url が含まれます。自分で /dav を組み立てず、返されたアドレスを使います。完全に設定された White Label メールゾーンにはブランド DAV ホスト名、それ以外には稼働中のプラットフォームホスト名が返されます。

推奨トークンパターン

スコープがない場合

必要な Drive スコープがなければ、API は権限エラーを返します。制限によってメールボックスやリソースが対象外なら、見つからないという応答を返す場合があります。これにより非公開のアカウント構造を守ります。