Secure Drive Access for AI Agents

Give AI agents precisely scoped access to Google Drive, Google Docs, and Google Sheets — without handing over your entire cloud storage. PortEden's Drive Access API acts as a data firewall between your AI tools and your files.

The Problem: AI Agents Need File Access, Not Full Access

Modern AI agents and workflows need to interact with your files — reading project briefs, updating spreadsheets, searching for documents, editing proposals. But giving an agent a raw Google Drive OAuth token is the equivalent of handing over your house keys when someone only needs to check your mailbox.

Common risks with direct Drive access:

Over-permissioned access — an agent that only needs to read one spreadsheet gets access to every file in your Drive
No operation boundaries — a "read-only" task could accidentally delete, share, or modify files
No file-level filtering — confidential HR documents, financial models, and personal files are all exposed
Credential sprawl — OAuth tokens stored in agent configs, tool chains, and third-party services
No audit trail — when something goes wrong, there's no record of what the agent accessed

The Solution: A Data Firewall for Google Drive

PortEden's Drive Access API sits between your AI agents and Google Drive. Instead of giving agents direct OAuth credentials, you issue PortEden Access Tokens with precisely scoped permissions. Every request passes through three security layers before touching your files.

How It Works

Connect your Google account

Link your Google Drive through a Custom OAuth app at my.porteden.com. Your OAuth credentials stay in PortEden — agents never see them.

Create an Access Token with Drive permissions

Choose which operations the token can perform, which files it can access, and what fields are visible. See Permissions.

Give the token to your AI agent

The agent calls the Drive Access API with the token. PortEden enforces all permission checks, filters results, and proxies to Google Drive.

Three-Layer Security Model

Every Drive API request passes through three independent security layers. A request must satisfy all three to succeed.

Layer 1: Operation Permissions

Control what the agent can do. Each token has a bitflag that enables or disables specific operations — search files, upload, rename, delete, read docs, write sheets, and more. An agent with read_only permissions literally cannot modify, delete, or share anything.

Common Permission Presets

Preset	What It Allows
read_only (default)	List, search, view metadata, get download/export links
docs_read_only	Read Google Docs text content
sheets_read_only	Read Google Sheets cell values and metadata
docs_all	Read + edit Google Docs
sheets_all	Read + write + append Google Sheets
workspace_all	All Docs + Sheets operations
all	Every operation including upload, delete, share

Layer 2: Drive Rules (File-Level Firewall)

Control which files the agent can see. Drive rules act as an allowlist or blocklist at the file level. You can scope access by:

Specific file IDs — grant access to exactly the files the agent needs
Folders — allow or block entire folder trees
MIME types — allow only PDFs, only spreadsheets, or block specific formats

Block rules always override allow rules, so you can create broad access with surgical exclusions (e.g., "access everything except the HR folder").

Layer 3: Field Visibility

Control what data the agent can read about files. Even when a file is accessible, you can mask sensitive metadata fields — hiding owner emails, descriptions, sharing info, or download links. Fields not in the token's visible set are returned as null.

What Agents Can Do with Drive Access

Search & Browse Files

Full-text search across file names and content. Filter by folder, MIME type, date range, ownership. Paginate large result sets.

Read & Export Files

Get file metadata, view/download links, and export Google Workspace files to PDF, DOCX, XLSX, CSV, and more.

Manage Files

Upload new files (up to 100 MB), create folders, rename, move between folders, trash, and manage sharing permissions.

Read & Edit Google Docs

Read document text in plain or structured format. Insert, append, or find-and-replace text — up to 100 operations per request.

Read & Write Google Sheets

Get spreadsheet metadata and sheet tab info. Read cell ranges, write values (with formula support), and append rows to existing data.

Inspect Permissions

View who has access to a file — owners, editors, viewers, and public links. Understand the sharing state before taking action.

Real-World Use Cases

AI Research Assistant

An AI agent that searches your Drive for relevant documents, reads their content, and synthesizes answers — without being able to modify or share any files.

Permissions: read_only + docs_read_only
Drive rules: Allow specific project folders only

Automated Report Builder

A workflow that reads data from a Google Sheet, generates a summary, and writes it back — scoped to specific spreadsheets in a reporting folder.

Permissions: sheets_all
Drive rules: Allow only the reporting folder

Document Drafting Agent

An agent that creates Google Docs, writes initial drafts, and performs find-and-replace edits — limited to a "Drafts" folder so it can't touch published documents.

Permissions: upload_file + docs_all
Drive rules: Allow Drafts folder only, block everything else

Data Pipeline Ingestion

An automated pipeline that searches for new CSV and Excel files, reads their content, and processes them — without access to any other file types.

Permissions: read_only
Drive rules: Allow only text/csv and application/vnd.openxmlformats-officedocument.spreadsheetml.sheet MIME types

Team File Organizer

An agent that organizes a shared Drive — creating folders, renaming files to follow naming conventions, and moving files into the right locations.

Permissions: list_files + create_folder + rename_file + move_file
Drive rules: Allow the shared team folder

Quick Start

Get an AI agent reading your Drive files in three steps.

1. Set Up Google OAuth

The platform-managed Google client doesn't request Drive permissions. You'll need a Custom OAuth app. Follow the Google OAuth Setup guide, ensuring you include the https://www.googleapis.com/auth/drive scope (or drive.readonly for read-only access).

2. Create an Access Token

At my.porteden.com, create an Access Token with:

driveAccessEnabled: true
The operation permissions your agent needs (default: read_only)
Drive rules to scope which files are accessible (default: block all unless rules match)

3. Make Your First API Call

curl -H "Authorization: Bearer pe_k1_your_token_here" \ 
  "https://cliv1b.porteden.com/api/access/drive/files?q=budget+report&limit=5"

The response includes only files the token is allowed to access, with only the fields the token is allowed to see.

Configuration Examples

Read-only access to a specific folder

{ 
  "driveAccessEnabled": true, 
  "allowedDriveOperations": "read_only", 
  "driveAllowAll": false, 
  "driveRules": [ 
    { "ruleType": "folder", "pattern": "google:0B7_PROJECT_FOLDER", "action": "allow" } 
  ] 
}

Full access except confidential content

{ 
  "driveAccessEnabled": true, 
  "allowedDriveOperations": "all", 
  "driveAllowAll": true, 
  "driveRules": [ 
    { "ruleType": "folder", "pattern": "google:0B7_HR_CONFIDENTIAL", "action": "block" }, 
    { "ruleType": "folder", "pattern": "google:0B7_LEGAL_PRIVATE", "action": "block" }, 
    { "ruleType": "mime_type", "pattern": "application/vnd.google-apps.spreadsheet", "action": "block" } 
  ] 
}

Sheets-only access for data processing

{ 
  "driveAccessEnabled": true, 
  "allowedDriveOperations": "sheets_all", 
  "driveAllowAll": false, 
  "driveRules": [ 
    { "ruleType": "mime_type", "pattern": "application/vnd.google-apps.spreadsheet", "action": "allow" } 
  ] 
}

Integrating with AI Agents

The Drive Access API is designed for AI agent consumption. Every response includes an accessInfo field — a human-readable summary of the token's restrictions that AI agents can use to understand their own limitations and communicate them to users.

Example accessInfo

{ 
  "accessInfo": "Read-only drive access, cannot upload, create, rename, move, delete, or share files. Drive is in block-all mode: only files matching allow rules are accessible. The user can adjust these permissions at https://my.porteden.com" 
}

This means an AI agent can:

Understand why a request was denied without guessing
Tell the user exactly what permissions need to change
Avoid attempting operations it doesn't have permission for
Link users to the permissions dashboard to self-service access changes

For MCP & Tool-Use Agents

When building MCP servers or tool-use agents, expose each Drive endpoint as a separate tool. Use the operation permission names as tool names (e.g., search_files, read_doc_content, write_sheet_data) so the agent can map capabilities directly.

Security Best Practices

✓

One token per agent, per use case

Don't reuse tokens across agents. Each agent should have its own token scoped to exactly what it needs.

✓

Start with read_only, add permissions as needed

The default permission is read_only. Only add write, delete, or share permissions when the agent genuinely needs them.

✓

Use folder-based rules for broad scoping

Rather than listing individual files, scope access to specific folders. This is easier to maintain and auditable.

✓

Block confidential folders explicitly

If using driveAllowAll: true, add block rules for HR, legal, and other sensitive folders. Block rules always override allow rules.

✓

Use drive.readonly scope when write access isn't needed

Connect your Google account with the drive.readonly scope if the agent only needs to read. Even if the token has write permissions, the Google connection will prevent writes.

✓

Revoke tokens promptly

When an agent is decommissioned or a use case ends, revoke the token at my.porteden.com or via the Token Management API.

PortEden vs. Direct Google Drive OAuth

Feature	Direct OAuth	PortEden Drive Access
Operation scoping	All-or-nothing (scope-level only)	16 individual operation flags + shorthand presets
File-level filtering	None — full Drive access	Allow/block by file ID, folder, or MIME type
Field masking	None — all metadata exposed	Configurable visible fields per token
Token revocation	Revoke entire OAuth grant	Revoke individual tokens independently
Multi-agent support	Share one OAuth token	Unique token per agent with independent permissions
AI-friendly responses	Raw Google API format	Normalized JSON with accessInfo for agent self-awareness
Google Docs editing	Requires separate Docs API setup	Built-in — same token, same base URL
Google Sheets access	Requires separate Sheets API setup	Built-in — same token, same base URL

API Reference

For complete endpoint documentation with request/response examples: