The real problem
Why this is harder than it looks
Most teams look at the Google Calendar API, see a clean REST interface, and estimate a day of work. The first user authorizing their calendar is genuinely easy. The problems appear once you move beyond a single developer account.
Google's OAuth app verification is the first wall. Because calendar write access is classified as a sensitive scope, any app with more than 100 external users must complete Google's OAuth verification process before the "This app isn't verified" warning disappears from the consent screen. That review typically takes 3–5 business days — longer if Google requests revisions. While your app is in testing mode, refresh tokens issued to external users expire after exactly 7 days regardless of activity. You won't see an error during development. You get a wave of invalid_grant errors in production a week after launch, as every user who authorized in testing mode simultaneously loses access.
Refresh tokens themselves are a source of silent failures. Google invalidates a refresh token if the user revokes access from their Google Account settings, changes their password (when the token includes Gmail-adjacent scopes), or if your app exceeds 100 refresh tokens per user per OAuth client. When that last limit is hit, Google silently invalidates the oldest token with no notification — meaning an active user can start getting 401s with no warning. Each of these cases requires different handling: detecting invalid_grant, re-initiating the auth flow, and surfacing it clearly to the user.
And then there's timezone handling. The Google Calendar API requires RFC3339 timestamps with explicit timezone offsets for all datetime fields. For recurring events, Google requires an IANA timezone identifier — not just a UTC offset — so the recurrence engine can expand rules correctly across DST transitions. Omitting it causes recurring events to shift by an hour after DST changes. Getting this right means knowing the user's calendar timezone at query time and threading it through every API call.
None of this is technically beyond a competent team. But it's weeks of edge-case work that doesn't make your agent smarter. Scalekit handles Google's token lifecycle, automatic refresh, revocation detection, and timezone-aware request routing so your agent can focus on what it's actually scheduling.
Capabilities
What your agent can do with Google Calendar
Once connected, your agent has 6 pre-built tools covering the full event and calendar management lifecycle:
- Create events with full scheduling options: attendees, Google Meet links, recurrence rules (iCalendar RRULE format), location, and IANA timezone support
- List and filter events: by time range, free-text search query, recurring event expansion into single instances, and pagination across large calendars
- Retrieve a specific event by ID: including attendee response status, recurrence metadata, and conference data
- Update existing events: patch any field without overwriting the rest — attendees, meeting links, duration, recurrence, and rescheduling all supported
- Delete events: idempotent deletion with optional attendee notification
- List all accessible calendars: enumerate primary, secondary, and shared calendars — essential for agents that work across multiple calendar contexts
Setup context
What we're building
This guide connects a scheduling assistant agent to Google Calendar — helping users create meetings, check availability, and manage their calendar without leaving your product.
🤖
Example agent
Scheduling assistant creating and managing calendar events 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="googlecalendar",
identifier="user_gcal_123" # 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 the correct Google Calendar scopes, PKCE challenge, and access_type=offline pre-configured to ensure refresh tokens are issued. After approval, you never see the token.
if connected_account.status != "ACTIVE":
link = actions.get_authorization_link(
connection_name="googlecalendar",
identifier="user_gcal_123"
)
# Redirect user → Google 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. Access
tokens refresh proactively before expiry. If a user revokes access from their Google Account settings or the
token is invalidated for any reason — including Google's invalid_grant conditions — the account moves to
REVOKED with no silent failures. Check account.status before critical operations.
Bring Your Own Credentials — required before production
For production deployments, register your own Google Cloud project with the Google Calendar API enabled,
configure the OAuth consent screen, and supply your Client ID and Secret in the Scalekit dashboard. This
ensures users see your app name on the consent screen and that your app's verification status governs the
token lifecycle. Token management stays fully handled.
Already have credentials?
Calling Google Calendar
4 Calling Google Calendar: 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 request construction.
List upcoming events
Fetch events within a time window. Use time_min and time_max in RFC3339 format. Set single_events to True to expand recurring events into individual instances.
result = actions.execute_tool(
identifier="user_gcal_123",
tool_name="googlecalendar_list_events",
tool_input={
"time_min": "2026-03-18T00:00:00Z",
"time_max": "2026-03-25T00:00:00Z",
"single_events": True,
"max_results": 20
}
)
# Returns list of events with id, summary, start, end, attendees
Create an event
Create a meeting with attendees and a Google Meet link. start_datetime is required in RFC3339 format. timezone should be an IANA identifier — e.g. America/New_York — to ensure the event renders correctly in the user's calendar.
result = actions.execute_tool(
identifier="user_gcal_123",
tool_name="googlecalendar_create_event",
tool_input={
"summary": "Q2 Planning — Engineering",
"start_datetime": "2026-04-01T10:00:00",
"timezone": "America/New_York",
"event_duration_hour": 1,
"attendees_emails": ["alice@example.com", "bob@example.com"],
"create_meeting_room": True,
"description": "Quarterly planning session. Agenda in Notion."
}
)
# Returns: { "id": "event_id", "htmlLink": "...", "hangoutLink": "..." }
Create a recurring event
Recurrence rules follow the iCalendar RRULE format. For recurring events, the timezone field is required — Google uses it to expand recurrences correctly across DST transitions.
result = actions.execute_tool(
identifier="user_gcal_123",
tool_name="googlecalendar_create_event",
tool_input={
"summary": "Weekly Standup",
"start_datetime": "2026-04-06T09:30:00",
"timezone": "Europe/London",
"event_duration_minutes": 30,
"recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"],
"attendees_emails": ["team@example.com"]
}
)
Update an event
Only the fields you supply are modified — other fields remain untouched. Use this to reschedule, add attendees, or attach a Meet link to an existing event.
result = actions.execute_tool(
identifier="user_gcal_123",
tool_name="googlecalendar_update_event",
tool_input={
"calendar_id": "primary",
"event_id": "abc123def456",
"start_datetime": "2026-04-01T14:00:00",
"timezone": "America/New_York",
"event_duration_hour": 1,
"send_updates": True
}
)
Framework wiring
5 Wiring into your agent framework
Scalekit integrates directly with LangChain. The agent decides what to schedule or 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
gcal_tools = get_tools(
connection_name="googlecalendar",
identifier="user_gcal_123"
)
prompt = ChatPromptTemplate.from_messages([
("system", "You are a scheduling assistant. Use the available tools to help manage the user's Google Calendar. Always confirm timezone before creating events."),
MessagesPlaceholder("chat_history", optional=True),
("human", "{input}"),
MessagesPlaceholder("agent_scratchpad"),
])
agent = create_tool_calling_agent(ChatAnthropic(model="claude-sonnet-4-6"), gcal_tools, prompt)
result = AgentExecutor(agent=agent, tools=gcal_tools).invoke({
"input": "Schedule a 1-hour team sync with alice@example.com next Monday at 10am Eastern, with a Google Meet link"
})
Other frameworks supported
Tool reference
All 6 Google Calendar tools
Grouped by operation type. Your agent calls tools by name — no API wrappers to write.
googlecalendar_create_event
Create a new event with attendees, Google Meet link, recurrence rules (iCalendar RRULE), location, and IANA timezone. summary and start_datetime are required.
googlecalendar_list_events
List events from a calendar with time range filters, free-text search, and optional expansion of recurring events into single instances
googlecalendar_get_event_by_id
Retrieve a specific event by ID. Supports optional time range filters, deleted event inclusion, and recurring event instance expansion
googlecalendar_update_event
Update an existing event. Only supplied fields are modified. Supports rescheduling, attendee changes, adding Meet links, and sending update notifications to attendees
googlecalendar_delete_event
Delete an event by ID. Idempotent — safe to call if the event may already be deleted
googlecalendar_list_calendars
List all accessible calendars for the authenticated user, including secondary and shared calendars. Supports pagination, access role filters, and hidden calendar inclusion
Connector notes
Google Calendar-specific behavior
OAuth app verification is required for production
Google Calendar write access is a sensitive scope. Until your Google Cloud project completes OAuth
verification, external users see an "app isn't verified" warning and refresh tokens expire after 7 days.
Complete verification before launch — the review process takes 3–5 business days. If you're building for
an internal Google Workspace org only, set your app's user type to Internal to bypass external
verification entirely.
Timezone field is required for recurring events
When creating recurring events, always include the timezone field as an IANA identifier (e.g.
America/Chicago, not UTC-6). Google uses this to expand recurrence rules correctly across DST transitions.
Omitting it causes recurring events to shift by an hour after DST changes, and the recurrence field will
be rejected entirely if timezone is missing.
Refresh tokens have multiple silent invalidation triggers
Google can invalidate a refresh token when: the user revokes access in their Google Account settings, the
token has been idle for 6 months, or your app exceeds 100 active refresh tokens per user per OAuth client.
That last case is especially dangerous — Google invalidates the oldest token silently with no notification.
Scalekit detects all of these as REVOKED status and stops your agent from making further calls on behalf
of that user.
Infrastructure decision
Why not build this yourself
The Google Calendar OAuth flow is documented. Token storage isn't technically hard. But here's what you're actually signing up for:
PROBLEM 01
Google OAuth app verification — a multi-day review process that blocks production launch, with refresh tokens expiring after 7 days in testing mode
PROBLEM 02
Silent invalid_grant failures from multiple distinct refresh token invalidation conditions, each requiring different detection and remediation logic
PROBLEM 03
Timezone-aware event creation — RFC3339 formatting, IANA identifiers for recurring events, and DST-safe recurrence expansion across user calendar timezones
PROBLEM 04
Per-user token isolation with multi-tenant storage — 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 Salesforce, Gmail, Slack, 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.
