Google Sheets does not hand out API access by default. If you want to read or write spreadsheet data from code, a cron job, or an AI agent like Openclaw, you need credentials from Google Cloud Console. The most common path for server-to-server access is a service account — a bot identity that authenticates with a JSON key file instead of a browser login.
The whole setup takes about 10 minutes. You will create a Google Cloud project, enable the Sheets API, generate a service account with a downloadable JSON key, and share your target spreadsheet with the service account’s email address. After that, any tool or script that can load the JSON file can read and write your sheets.
Before walking through the steps, it helps to understand why there are three different credential types and which one you need.
API Key vs. OAuth vs. Service Account
Google Cloud offers three authentication methods for the Sheets API. Picking the wrong one is the most common reason developers get stuck before writing a single line of code.
API keys are the simplest. They identify your project and work for reading public spreadsheets only. No user login, no JSON file, no sharing step. The catch: they cannot access private sheets and cannot write data. If your spreadsheet is not published to the web, an API key will not help.
OAuth 2.0 client credentials prompt a real user to log in via a consent screen. This is the right choice for apps where end users grant access to their own spreadsheets — think a web app that lets someone connect their Google account. It is the wrong choice for automated scripts, CI pipelines, or AI agents that run without a human clicking “Allow.”
Service accounts are what you want for server-to-server access. A service account is a bot email address (like my-bot@my-project.iam.gserviceaccount.com) that authenticates using a private key stored in a JSON file. You share your spreadsheet with that email exactly like you would share it with a colleague. No consent screen, no browser, no token refresh headaches.
| Method | Use Case | Accesses Private Sheets | Requires User Login |
|---|---|---|---|
| API Key | Public read-only data | No | No |
| OAuth 2.0 | End-user apps with consent | Yes | Yes |
| Service Account | Servers, scripts, AI agents | Yes | No |
For everything in this guide, we are using a service account. If you just need to read a public sheet, skip to the FAQ section for the simpler API key route.
Step 1: Create a Google Cloud Project
Go to console.cloud.google.com and sign in with the Google account that owns (or has access to) the spreadsheets you want to connect.
Click the project dropdown in the top navigation bar and select New Project. Give it a descriptive name — something like sheets-integration or openclaw-sheets. The project ID is auto-generated; leave it as-is unless you have a naming convention.
Click Create. It takes a few seconds. Make sure the new project is selected in the dropdown before moving to the next step. This is an easy thing to overlook: if you have multiple Cloud projects, the Console sometimes defaults back to a different one.
Step 2: Enable the Google Sheets API
With your new project selected, navigate to APIs & Services > Library from the left sidebar (or search “Sheets API” in the top search bar).
Find Google Sheets API and click Enable. That is it — one click. The API is free for most usage. Google imposes rate limits of 500 requests per 100 seconds per project and 100 requests per 100 seconds per user, but you are unlikely to hit those unless you are polling a sheet in a tight loop.
If you also need to create new spreadsheets programmatically (not just read/write existing ones), enable the Google Drive API as well. The Sheets API handles cell data; the Drive API handles file-level operations like creating, deleting, and listing spreadsheets.
Step 3: Create a Service Account
Navigate to APIs & Services > Credentials in the left sidebar. Click Create Credentials and select Service Account.
Fill in the details:
- Service account name: Something descriptive like
sheets-readeroropenclaw-integration - Service account ID: Auto-generated from the name. This becomes the email address.
- Description: Optional but helpful. “Read/write access to project spreadsheets” is fine.
Click Create and Continue. The next screen asks about roles. For basic Sheets access, you do not need to assign any IAM roles here — the service account gets its spreadsheet permissions through sharing, not through Cloud IAM. Click Continue, then Done.
You will see your new service account listed on the Credentials page. Note the email address — it follows the pattern SERVICE-NAME@PROJECT-ID.iam.gserviceaccount.com. You will need this in Step 5.
Step 4: Download the JSON Key
Click on the service account name to open its detail page. Go to the Keys tab. Click Add Key > Create New Key. Select JSON as the key type and click Create.
Your browser downloads a .json file. This file contains the private key that authenticates your service account. Treat it like a password.
A few important rules for managing these files:
- Never commit it to Git. Add the filename to
.gitignoreimmediately. Developers who push keys to public repos get abuse notifications from Google within hours. - Use environment variables in production. Store the JSON content (or its file path) in an environment variable rather than hardcoding a path. Most deployment platforms (Railway, Render, Vercel, AWS) support secret environment variables.
- Rotate keys periodically. You can create multiple keys for the same service account. Create a new one, update your deployment, then delete the old one. Google recommends this but does not enforce it.
- Use the narrowest scope possible. If your application only reads data, use the
spreadsheets.readonlyscope. Only usespreadsheets(full read/write) when you genuinely need to write.
Step 5: Share Your Spreadsheet with the Service Account
Open the Google Sheet you want to access. Click the Share button in the top right. Paste the service account email address (the one from Step 3, ending in iam.gserviceaccount.com) and set the permission level:
- Viewer: Read-only access
- Editor: Read and write access
Click Send. Google may warn that “this email address is not associated with a Google account” — ignore it and confirm.
This step is where most developers get stuck. The service account starts with zero access to zero spreadsheets. It can only see sheets that have been explicitly shared with its email. Every new sheet you want to connect requires this sharing step.
If you are working with many sheets, consider creating a shared Google Drive folder, sharing the folder with the service account, and placing all relevant sheets inside it. The service account inherits folder-level permissions.
Verify Your Setup
Before building anything on top of these credentials, confirm the connection works. Here is a quick test using the Google API client library for Python.
Using the Google API client library (Python):
from google.oauth2.service_account import Credentials
from googleapiclient.discovery import build
creds = Credentials.from_service_account_file(
'your-key-file.json',
scopes=['https://www.googleapis.com/auth/spreadsheets.readonly']
)
service = build('sheets', 'v4', credentials=creds)
# Replace with your spreadsheet ID (from the URL)
sheet_id = 'YOUR_SPREADSHEET_ID'
result = service.spreadsheets().values().get(
spreadsheetId=sheet_id,
range='Sheet1!A1:B5'
).execute()
print(result.get('values', []))
The spreadsheet ID is the long string in the URL between /d/ and /edit. If the script prints your cell values, the setup is working. If you get a 403 error, double-check that you shared the sheet with the correct service account email.
Connect Your Service Account to Openclaw
Once you have the JSON key file, connecting to Openclaw’s Google Sheets integration takes about five more minutes. Openclaw uses the same service account credentials to read from and write to your spreadsheets through natural language commands.
The setup involves adding your JSON key contents to Openclaw’s environment variables and writing a SKILL.md file that defines what the agent can do with your sheets — log expenses, update CRM rows, pull reporting data, or anything else you wire up. The full integration guide covers the SKILL.md syntax and example workflows.
If you are evaluating other API key setups for Openclaw, we have similar walkthroughs for OpenAI, Anthropic, and Google Gemini.
Common Errors and Fixes
These are the issues we see most often when developers set up Sheets API access for the first time.
“The caller does not have permission” (403) The spreadsheet has not been shared with the service account email. Open the sheet, click Share, paste the service account email. This fixes it every time.
“Google Sheets API has not been enabled” (403) Go back to APIs & Services > Library and make sure the Google Sheets API is enabled for the correct project. Check the project dropdown — Cloud Console sometimes switches you to a different project silently.
“Invalid grant” or “Could not deserialize key data” The JSON key file is corrupted or incomplete. Download a fresh key from the service account’s Keys tab. If you stored the key as an environment variable, make sure you preserved the newlines in the private key field.
“Quota exceeded” (429)
You have hit the rate limit (500 requests per 100 seconds per project). Add exponential backoff to your requests, or batch multiple read/write operations into a single API call using batchUpdate or batchGet.
Frequently Asked Questions
Is the Google Sheets API free to use?
For most projects, yes. Google does not charge for Sheets API calls. The free tier includes 500 requests per 100 seconds per project and 100 per user. You do not need to enable billing to use it. The only scenario where costs come into play is if you exceed Cloud Platform quotas on other services within the same project.
What is the difference between an API key and a service account?
An API key is a simple string that identifies your project. It only works for reading publicly shared spreadsheets. A service account is a full identity with its own email address and private key, capable of accessing private sheets that have been shared with it. For any real application that works with private data, you need a service account.
Do I need to enable billing on Google Cloud for this?
No. You can create a Cloud project, enable the Sheets API, and create a service account without ever adding a credit card. The Sheets API is free within standard rate limits.
What scopes should I request?
Use https://www.googleapis.com/auth/spreadsheets.readonly if you only read data. Use https://www.googleapis.com/auth/spreadsheets for read and write. Avoid requesting broader scopes like drive unless you specifically need to create or delete spreadsheet files.
Can I use one service account for multiple spreadsheets?
Yes. Share each spreadsheet with the same service account email. There is no limit to how many sheets a single service account can access.
How do I store the JSON key in a CI/CD pipeline?
Most CI platforms (GitHub Actions, GitLab CI, CircleCI) support secret environment variables. Base64-encode the JSON file contents, store it as a secret, and decode it at runtime. Never check the raw JSON file into your repository.
Why does my service account email not look like a real email?
Because it is not one. The format name@project.iam.gserviceaccount.com is a special identity managed by Google Cloud. It authenticates via private key, not password. When you share a sheet with it, Google treats it like any other collaborator.
What happens if my JSON key file is leaked?
Delete the key immediately from the service account’s Keys tab in Cloud Console. Create a new key and update your deployments. The old key is revoked instantly. If you suspect misuse, check the Cloud Console audit logs for unauthorized API calls.
Key Takeaways
- Use a service account (not an API key or OAuth) for server-to-server Google Sheets access from scripts, backends, and AI agents.
- The setup takes about 10 minutes: create a Cloud project, enable the Sheets API, generate a service account with a JSON key, and share your sheet with the service account email.
- The JSON key file is your credential — store it in environment variables, never in Git, and rotate it periodically.
- Test the connection with a simple script before building anything on top of it.
- If you are connecting Sheets to an AI agent, the Openclaw Google Sheets integration guide picks up where this article ends.
SFAI Labs
