Drive API Scopes and Permissions

Drive scopes decide exactly what an API token or MCP agent can do with TrekMail Drive. A good token is narrow: it has the smallest set of scopes needed for one job, a clear name, and an expiration date.

The Drive API adds 9 scopes across Account Drive, mailbox Drive, share links, permanent delete, and read-only Drive Add-on status. These scopes belong to ops tokens (tm_live_...). Message tokens (tm_msg_...) are still for email operations.

Scope reference

Read, write, share, purge

Drive separates common tasks into four permission levels:

• Read can list spaces, browse folders, inspect metadata, view trash, and request download URLs.
• Write can upload, create folders, rename, move, trash, and restore.
• Share can create, list, and revoke public share links.
• Purge can permanently delete trashed items or empty trash.

Do not give purge to a general-purpose assistant. If you need automated cleanup, create a separate token named for that job, keep it disabled in MCP until needed, and review the audit log after each run.

Plan and add-on access

Drive API access is available when the account has Drive entitlement through a paid plan or an active Drive Storage Add-on. A free account with an active add-on can use Drive scopes for storage automation, similar to how Email Verifier scopes are available independently of full infrastructure API access.

If a Drive Add-on is canceled and enters its grace window, read access can remain available so files can be reviewed and exported. Write, share, and purge access may be restricted until the account returns to an active storage state.

Account Drive versus mailbox Drive

Account Drive scopes and mailbox Drive scopes are intentionally separate. A billing or operations agent may need Account Drive only. A mailbox assistant may need access to one mailbox Drive and nothing else.

Use mailbox constraints when creating a token for mailbox automation. A constrained token can only see allowed mailbox spaces. Requests for other mailboxes return a not-found style response, which avoids leaking account structure to a narrowly scoped integration.

Drive Add-on scope is read-only

drive:addon:read lets an agent read add-on status, pricing, and cancellation preview. It cannot buy storage, resize an add-on, cancel a subscription, or trigger a payment action.

That boundary is deliberate. Storage billing changes stay in the dashboard, where a human can review capacity, price, currency, billing period, and payment confirmation. There is no drive:addon:write scope.

Recommended token patterns

What happens when a scope is missing

If a token lacks the required Drive scope, the API returns a permission error. If the token is constrained away from a mailbox or resource, the API may return not found. This protects private account structure from integrations that should not know it.