Drive Sync Architecture: URLs, Scopes, Audit

This is the developer-facing reference for Drive Sync. If you're integrating sync access alongside the REST API or MCP server, building tooling on top of TrekMail Drive, or auditing how the WebDAV facade enforces permissions, this is the page.

If you just want to connect rclone or Finder to Drive, start with Drive Sync overview.

What Drive Sync is

Drive Sync is a WebDAV interface to TrekMail Drive. It gives a compatible sync app access to the same files you see in the dashboard and webmail, with its own device password and selected permissions.

The interface uses standard WebDAV methods at a fixed prefix. Client support differs, so test the operations your client needs with a disposable folder before using it for a production migration or backup.

URL layout

The Drive URL is generated for the deployment and shown on Sync devices. Copy that URL instead of building one from your dashboard domain. Its path begins with /dav/files/:

https://YOUR-DRIVE-HOST/dav/files/

Below that root are an account tree and mailbox trees. What a password can open depends on both its mailbox binding and its selected permissions:

Account-wide tree

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

This is the dashboard's account Drive. A password that is not limited to one mailbox can see this tree when it has an account Drive permission.

Mailbox-scoped tree

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

When a device password is restricted to one mailbox, it can see only that mailbox’s personal tree. If the mailbox has personal Drive access and the account has shared folders, the Shared/ collection shows the account folders shared with all mailboxes.

A password limited to one mailbox cannot see Account Drive or another mailbox. A password without a mailbox limit can list the account’s Drive spaces, but each path still requires its matching account or mailbox permission.

Create a device password

You can create a password from Sync devices in the dashboard or, for the mailbox you are currently using, from webmail. The dashboard can create an account-wide password or limit it to one mailbox. Webmail creates a password only for the signed-in mailbox.

Choose a clear label, select only the permissions the app needs, and set an expiry when the connection is temporary. The secret is shown once. Save it in the app or a password manager before closing the confirmation screen.

You can revoke a device password at any time without changing your normal TrekMail sign-in password. A revoked or expired password stops working immediately.

Sign in with a device password

Sync uses HTTP Basic over HTTPS. Enter the username displayed on Sync devices and the generated device password. Do not use your TrekMail dashboard password in a sync app.

If the password is revoked or expires, the app normally asks for credentials again. Account status, mailbox access, Drive access, and the permissions you selected are checked for each request.

Scope model

Drive Sync uses the same scope strings as the REST API, in the drive:{family}:{action} form. The eight that apply to device passwords:

Reading a path needs its matching :read permission. Creating, changing, moving, copying, or deleting needs :write. The path determines whether the app is asking for account or mailbox access, so a password limited to one mailbox cannot reach Account Drive or another mailbox.

The Sync devices screen offers only permissions that make sense for a sync app. Billing permissions are not part of a device password.

Share and purge permissions

The device-password form can show :share and :purge permissions when the account is entitled to them. The current WebDAV route guard maps file operations only to :read and :write, so do not assume that selecting either permission adds a WebDAV share-link or permanent-delete command.

For WebDAV, regular DELETE requires :write and moves a file to Trash. WebDAV does not provide an in-place file replacement or a permanent-purge operation. Use the Drive interface for those tasks.

Filename safety

File and folder names must be safe on different operating systems. Empty names, path separators, control characters, misleading filename characters, and names that would collide after Windows or Unicode normalization are rejected. Names can be up to 255 visible characters.

If an app receives a validation error, rename the item in the app and try again. Do not try to work around the error by placing a path in a file name.

Chunked uploads

Small files can use a normal PUT. Clients that support the Nextcloud chunked-upload v2 flow can create an upload session under /dav/uploads/{session-uuid}/, upload numbered chunks, then use MOVE to assemble the file at its final location.

Upload limits can vary by deployment and client. Treat a failed or expired session as a new upload attempt. If another client creates the destination first, use the conflict response to choose a new name or refresh the folder before retrying.

Audit trail

Successful changes made through Sync appear in the Drive activity history. The record identifies the affected item, the action, the time, and the device password used, so an administrator can investigate unexpected changes and revoke the relevant password.

Clients that use the Drive change feed can see changes made through WebDAV. If the service asks for a full resync, rebuild the local view from a fresh snapshot before continuing with the saved cursor.

Rate limits

Drive Sync requests are rate-limited to protect the service and your files. If a client receives 429, reduce concurrency, honor Retry-After when it is supplied, and retry a small operation before resuming the job.

Availability

Drive Sync is available in production. Accounts need Drive access, and the available device-password permissions still depend on the account, mailbox, plan, and the person creating the password. White Label customers use the same Drive Sync service. Always copy the current URL from Sync devices rather than constructing one.

What's next

• For end-user setup, Drive Sync overview.
• For the dashboard UI that issues device passwords, Sync devices.
• For the REST API and MCP equivalents of these operations, Drive API Overview and Drive API Scopes & Permissions.
• For the storage and quota model that sync shares with everything else, Pooled Storage Quotas Explained.