Drive API 범위와 권한 상세 가이드

Drive 범위는 API 토큰이나 MCP 에이전트가 TrekMail Drive에서 할 수 있는 작업을 정확히 결정합니다. 좋은 토큰은 한 작업에 필요한 최소 범위, 명확한 이름, 만료일만 가집니다.

Drive API에는 계정 Drive, 사서함 Drive, 공유 링크, 영구 삭제, Drive 애드온 상태 및 동기화 장치 암호에 대한 11개 범위가 있습니다. 운영 토큰(tm_live_...)에 속하며 메시지 토큰(tm_msg_...)은 계속 이메일 작업에 사용됩니다.

범위 참조

읽기, 쓰기, 공유, 완전 삭제

Drive는 일반 작업을 네 단계로 나눕니다.

• 읽기는 공간과 폴더 조회, 메타데이터 확인, 휴지통 보기, 다운로드 URL 요청을 허용합니다.
• 쓰기는 업로드, 폴더 생성, 이름 변경, 이동, 휴지통 이동, 복원을 허용합니다.
• 공유는 공개 링크 생성, 조회, 취소를 허용합니다.
• 완전 삭제는 휴지통 항목의 영구 삭제 또는 휴지통 비우기를 허용합니다.

범용 도우미에게 완전 삭제를 주지 마세요. 자동 정리에는 작업 이름을 가진 별도 토큰을 만들고 필요할 때까지 MCP에서 비활성화하며 실행 후 감사 로그를 검토하세요.

요금제 및 애드온 액세스

유료 요금제나 활성 Drive 스토리지 애드온으로 Drive 권한이 있으면 Drive API를 사용할 수 있습니다. 활성 애드온을 가진 무료 계정도 전체 인프라 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 범위가 없으면 API는 권한 오류를 반환합니다. 제한으로 사서함이나 리소스가 제외되면 찾을 수 없음을 반환할 수 있습니다. 이를 통해 비공개 계정 구조를 보호합니다.