The fastest way to connect an AI agent to Google Sheets and Calendar is a service account: create it in Google Cloud Console, download its JSON key into secret storage, enable the Sheets and Calendar APIs with minimal scopes, and then do the step nearly every tutorial skips — share the actual Sheet and Calendar with the service account's email address, exactly as you would with a human collaborator. Miss that last step and you get the 403 error that has sent thousands of developers into their code looking for a bug that is not there. This is the exact setup running behind my production agents — the CRM-update and meeting-prep agents on this site both talk to Google Workspace this way — written as the checklist I wish I had had.
What a service account actually is
A service account is a machine identity: its own "user" with its own email address (something like agent-name@your-project.iam.gserviceaccount.com), authenticating with a cryptographic key instead of a password, with no login screen and no consent popup. This is fundamentally different from OAuth user login, where your code acts as a specific human who clicked "Allow". The distinction that trips up most first attempts: because the service account is its own user, it has access to nothing by default. It cannot see your Sheets. It cannot see your Calendar. It is a stranger until you explicitly invite it — which is the whole key to the setup, and we will get there in step 3. Use a service account when an agent acts as itself around resources you control; use OAuth when your product must act on behalf of arbitrary end users.
Step 1 — create the service account and protect the key
In Google Cloud Console: create (or pick) a project, go to IAM & Admin → Service Accounts, create one with a name that says what it does, and skip the optional project-role grants — Sheets and Calendar access will come from sharing, not IAM roles. Then create a key (JSON type) and it downloads once. That file is a credential that never expires on its own, so treat it accordingly: it goes in an environment variable or a secret manager, never in the repository. Add it to .gitignore before you do anything else, because a service-account key committed to git is compromised the moment the repo is shared — and if it ever does land somewhere it should not, rotate it immediately: create a new key, deploy it, delete the old one. Rotating periodically even without an incident is cheap insurance.
Step 2 — enable the APIs and choose narrow scopes
In the console's API library, enable the Google Sheets API and the Google Calendar API for your project — forgetting this produces its own distinctive error telling you the API has not been used in the project. Then choose scopes deliberately. If the agent only reads a Sheet, request spreadsheets.readonly, not the full spreadsheets scope; if it only manages events, calendar.events rather than the full calendar scope. Scope minimalism is not bureaucratic hygiene: a leaked key with read-only Sheets scope is a much smaller incident than one with write access to every calendar, and narrow scopes make any future security review of your agent dramatically easier. Request the least you need now; widening later is a one-line change.
Step 3 — share the Sheet and Calendar with the service account
ONE TACTIC A WEEK
This is the step that causes the majority of "my code is broken" moments, so here it is plainly: your service account must be explicitly shared on every resource it touches. For a Sheet, open it and share it with the service account's email address — Viewer for read-only, Editor for writes — exactly as if inviting a colleague. For a Calendar, open the calendar's settings, find "Share with specific people", add the service account's email, and pick the permission level ("Make changes to events" for an agent that books). There is no workspace-wide access by default and no hidden admin backdoor: one service account can access as many Sheets and Calendars as you like, but each one must be individually shared. When a teammate creates a new Sheet and the agent mysteriously cannot see it, this is why.
Step 4 — authenticate from your agent code
With googleapis in Node/TypeScript, the pattern is: construct a GoogleAuth (or JWT) client with the service-account credentials — supplied via an environment variable pointing at the key file, or the key's client_email and private_key fields injected from your secret manager — and the scopes you chose in step 2, then pass that auth client to google.sheets({ version: "v4", auth }) or google.calendar({ version: "v3", auth }). The library handles the JWT signing and token exchange; you never manage access tokens by hand. From there, reads and writes are plain calls: spreadsheets.values.get and append for Sheets, events.insert for Calendar. Two production habits worth adopting from day one: keep the spreadsheet and calendar IDs in configuration rather than scattered through code, and log Google's full error payloads — they are verbose JSON, and the verbosity is exactly what you want when something fails at 2am.
Step 5 — the Calendar-specific gotchas: freebusy and timezones
Sheets integration is mostly done at this point; Calendar has two traps left. First, never write an event blind — call the freebusy endpoint for the target window first and only insert if it is clear, because an agent that double-books is worse than no agent. Second, timezones: Calendar stores instants, and if your agent computes "tomorrow at 3pm" on a UTC server for a user in Dubai, you will create meetings four hours wrong. Normalise every datetime to an explicit timezone (for me, Asia/Dubai) before writing, and pass the timeZone field on the event rather than hoping defaults align. The wrong-time bug is nastier than the double-booking bug because nothing errors — the write succeeds, and the failure surfaces as a missed meeting. A confirm-before-write step, where the agent states the exact slot in local time before committing, catches both classes of bug and costs one message.
Common errors and what they actually mean
The decode table from production. 403 "The caller does not have permission": the resource is not shared with the service account's email — go to step 3; it is almost never your code. 404 "not found" on an ID you can see in your own browser: usually the same sharing problem wearing a different mask — Google returns 404 rather than confirming a resource exists to an identity with no access. 403 with "API has not been used in project": step 2, the API is not enabled. 429 or quota errors: you are hitting per-minute limits, so batch reads (one values.batchGet beats fifty gets) and add exponential backoff. invalid_grant on auth: malformed or revoked key — commonly private-key newlines mangled by an env-var layer; the \n sequences must survive into the actual key string. When in doubt, read the full error payload — Google's errors are wordy but they usually name the resource, the identity and the missing permission, which is everything you need.