The real problem
Why this is harder than it looks
Most teams look at the Google Drive API and assume the auth story is simple: get an OAuth token, call the API. The problem is that Google treats Drive access as a sensitive scope — and that changes everything about how your integration has to work.
In production, each of your users connects their own Google account. That means per-user token isolation across your entire tenant base, with refresh logic that has to run proactively before the one-hour access token window closes — not reactively after a failed call. If a user revokes your app from their Google Account settings, you need to detect the resulting 401 and stop making Drive calls on their behalf before they notice.
Then there's Google's OAuth verification process. Apps requesting access to Drive must go through Google's OAuth consent screen verification before external users can authorize without a warning screen. Until you complete it, users outside your Google Cloud project see a warning that says "Google hasn't verified this app." In a multi-tenant product, that warning will kill your activation rate. Navigating that process — and keeping your OAuth app configuration in sync with the scopes your agent actually uses — is ongoing maintenance work that has nothing to do with making your agent smarter.
There's also the Shared Drive problem. Many organizations store most of their important files in Shared Drives, not in personal My Drive. The Drive API requires the supportsAllDrives=true parameter to include Shared Drive results in file listings and metadata calls — without it, your agent silently misses files. Scalekit handles the token lifecycle, refresh scheduling, revocation detection, and the correct API parameters. Your agent calls a tool with a file ID or search term. Everything else is managed.
Capabilities
What your agent can do with Google Drive
Once connected, your agent can search and retrieve files across the full Drive corpus:
- Full-text content search: find files where the body text matches a search term, across Docs, Sheets, Slides, PDFs, and other indexed formats
- Structured file queries: filter by name, MIME type, parent folder, owner, or any Drive query field using Drive's query language
- File metadata retrieval: get name, MIME type, size, creation and modification timestamps, sharing settings, and custom fields for any file by ID
- Shared Drive support: all tools include support for Shared (Team) Drives alongside personal My Drive, so your agent doesn't silently miss org files
Setup context
What we're building
This guide connects a document assistant agent to Google Drive — helping users find files, surface relevant documents, and retrieve metadata without leaving your product.
🤖
Example agent
Document assistant finding and surfacing Drive files on behalf of each user
🔐
Auth model
B2B SaaS — each user connects their own Google account. identifier = your user ID
Setup
1 Setup: One SDK, One credential
Install the Scalekit SDK. The only credential your application manages is the Scalekit API key — no Google secrets, no user tokens, nothing belonging to your customers.
pip install scalekit-sdk-python
import scalekit.client
import os
from dotenv import load_dotenv
load_dotenv()
scalekit = scalekit.client.ScalekitClient(
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit.actions
Connected Accounts
2 Per-User Auth: Creating connected accounts
Each user gets their own Connected Account, giving them a dedicated auth context. The identifier is any unique string from your system — a UUID, email, whatever you use internally.
response = actions.get_or_create_connected_account(
connection_name="google_drive",
identifier="user_gdrive_456" # your internal user ID
)
connected_account = response.connected_account
print(f"Status: {connected_account.status}")
# Status: PENDING — user hasn't authorized yet
This call is idempotent — safe to call on every session start. Returns the existing account if one already exists.
Authorization Flow
3 The authorization flow
The user authorizes your agent once. Scalekit generates the OAuth URL with correct scopes, PKCE challenge, and redirect handling pre-configured. After approval, you never see the token.
if connected_account.status != "ACTIVE":
link = actions.get_authorization_link(
connection_name="google_drive",
identifier="user_gdrive_456"
)
# Redirect user → Google OAuth consent screen
# Scalekit captures the token on callback
return redirect(link.link)
Token management is automatic
After the user approves, Scalekit stores encrypted tokens and the connected account moves to ACTIVE. Google
Drive access tokens expire after one hour — Scalekit refreshes them before expiry. If a user revokes your app
from their Google Account, the account moves to REVOKED — no silent failures. Check account.status before
critical operations.
Bring Your Own Credentials — required for Google Drive
Google Drive requires you to register your own OAuth client in Google Cloud Console. Enable the Drive API,
create an OAuth 2.0 client ID (Web application), and add Scalekit's redirect URI under Authorized Redirect
URIs. Then paste your Client ID and Client Secret into the Scalekit dashboard. Token management stays fully
handled.
Already have credentials?
Calling Google Drive
4 Calling Google Drive: What your agent writes
With the connected account active, your agent calls actions using execute_tool. Name the tool, pass parameters. Scalekit handles token retrieval and the correct Drive API parameters including Shared Drive support.
Get file metadata by ID
Retrieve details about a specific file. Use fields to control which metadata comes back — name, MIME type, size, permissions, and more.
result = actions.execute_tool(
identifier="user_gdrive_456",
tool_name="googledrive_get_file_metadata",
tool_input={
"file_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
"fields": "id,name,mimeType,size,createdTime,modifiedTime,owners",
"supports_all_drives": True
}
)
# { "id": "...", "name": "Q3 Strategy.docx", "mimeType": "application/vnd.google-apps.document", ... }
Search files by name or type
Find files using Drive's query language. Filter by file name, MIME type, parent folder, or owner. Set supports_all_drives to include Shared Drives.
result = actions.execute_tool(
identifier="user_gdrive_456",
tool_name="googledrive_search_files",
tool_input={
"query": "name contains 'Q3' and mimeType = 'application/vnd.google-apps.spreadsheet'",
"fields": "files(id,name,modifiedTime,owners)",
"order_by": "modifiedTime desc",
"page_size": 10,
"supports_all_drives": True
}
)
# { "files": [ { "id": "...", "name": "Q3 Metrics", "modifiedTime": "2026-03-15T..." }, ... ] }
Full-text search inside file contents
Search the body text of Drive files — not just filenames. Finds documents that mention a specific topic, customer, or keyword. Supports MIME type filtering and pagination.
result = actions.execute_tool(
identifier="user_gdrive_456",
tool_name="googledrive_search_content",
tool_input={
"search_term": "annual renewal pricing",
"mime_type": "application/vnd.google-apps.document",
"fields": "files(id,name,modifiedTime)",
"page_size": 20,
"supports_all_drives": True
}
)
# Returns files whose full text contains the search term
# Works across Docs, Sheets, Slides, PDFs, and other indexed types
Framework wiring
5 Wiring into your agent framework
Scalekit integrates directly with LangChain. The agent decides what to look up; Scalekit handles auth on every invocation. No token plumbing in your agent logic.
from langchain_anthropic import ChatAnthropic
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from scalekit.langchain import get_tools
gdrive_tools = get_tools(
connection_name="google_drive",
identifier="user_gdrive_456"
)
prompt = ChatPromptTemplate.from_messages([
("system", "You are a document assistant. Use the available tools to help find and surface relevant files from the user's Google Drive."),
MessagesPlaceholder("chat_history", optional=True),
("human", "{input}"),
MessagesPlaceholder("agent_scratchpad"),
])
agent = create_tool_calling_agent(ChatAnthropic(model="claude-sonnet-4-6"), gdrive_tools, prompt)
result = AgentExecutor(agent=agent, tools=gdrive_tools).invoke({
"input": "Find the most recent document about our enterprise pricing and tell me who last edited it"
})
Other frameworks supported
Tool reference
Google Drive tools
3 pre-built tools. Your agent calls tools by name — no API wrappers to write. All tools support Shared Drives via the supports_all_drives parameter.
Search for files and folders using Drive query filters — name, MIME type, owner, parent folder, and any other Drive query field. Supports pagination and result ordering.
googledrive_search_content
Full-text search inside the content of Drive files. Finds files where the body text matches the search term, across Docs, Sheets, Slides, PDFs, and other indexed formats. Supports MIME type filtering and pagination.
googledrive_get_file_metadata
Retrieve metadata for a specific file by ID — name, MIME type, size, creation and modification times, owners, sharing settings, and any other Drive file fields. Supports Shared Drive files.
Connector notes
Google Drive-specific behavior
OAuth consent screen verification is required for production
Google requires apps requesting Drive access to complete an OAuth consent screen verification process before
external users can authorize without a warning screen. Until verification is complete, users outside your
Google Cloud project see a "Google hasn't verified this app" warning. Plan for this review process before
your production launch. For internal tools where all users are in your Google Workspace domain, you may be
able to limit access to internal users only and bypass the public verification requirement.
Shared Drive files are invisible without supportsAllDrives
The Drive API excludes Shared Drive files from search results and metadata lookups by default unless the
request includes supportsAllDrives=true. Scalekit handles this automatically when you pass
"supports_all_drives": true in your tool input. For organizations that store most files in Shared Drives,
omitting this parameter means your agent silently returns incomplete results.
Drive scopes and what they grant
The scope you configure in the Scalekit dashboard controls what your agent can do.
https://www.googleapis.com/auth/drive.readonly covers file metadata and content search.
https://www.googleapis.com/auth/drive.metadata.readonly provides metadata only, without content search.
Use the most restrictive scope that meets your agent's needs — Google's review process is more stringent
for broader scopes. Changing the scope after users have authorized requires re-authorization.
Infrastructure decision
Why not build this yourself
The Google Drive OAuth flow is documented. Token storage isn't technically hard. But here's what you're actually signing up for:
PROBLEM 01
Google access tokens expire after one hour — proactive refresh logic has to run before expiry, not in response to a failed call mid-operation
PROBLEM 02
Revocation detection when users disconnect your app from Google Account settings — and graceful handling so the agent stops making calls immediately
PROBLEM 03
Scope management across your tenant base — adding new Drive capabilities later requires re-authorization from all users who connected with the old scope set
PROBLEM 04
Per-user token isolation in a multi-tenant system — one user's Google credentials must never be accessible to another, even within the same organization
That's one connector. Your agent product will eventually need Gmail, Google Calendar, Salesforce, Notion, and whatever else your customers ask for. Each has its own OAuth quirks and failure modes.
Scalekit maintains every connector. You maintain none of them.
