# Google Service Account

> Connect Google Sheets, Docs, and Drive using a service account.

**URL:** https://inference.sh/docs/credentials/google-service-account
**Last updated:** 2026-09-24

---

Connect Google Sheets, Docs, and Drive using a service account.

---

## Overview

A service account is a dedicated email address created for your workspace. You share Google resources with this email to grant your agents access.

**Best for:**
- Shared spreadsheets
- Company Drive folders
- Public or shared Google resources

---

## How it works

```
1. Connect → We create a service account email
2. Share → You share your Google Sheet/Doc/Drive with that email
3. Access → Your agents can read/write the shared resources
```

No OAuth consent screens, no personal account linking — just simple file sharing.

---

## Connecting

1. Go to **vaults**, open the default vault's **credentials** tab, or open [Google Service Account](https://app.inference.sh/credentials/google-sa) directly
2. Click **Connect**
3. Copy the generated email (e.g., `agent-yourteam@inference-prod.iam.gserviceaccount.com`)

That's it — the service account is ready to use.

---

## Sharing resources

### Google Sheets

1. Open your Google Sheet
2. Click **Share** (top right)
3. Paste the service account email
4. Choose permission:
   - **Viewer** — read-only access
   - **Editor** — read and write access
5. Click **Send** (uncheck "Notify people" if you want)

### Google Docs

Same process as Sheets:

1. Open your Google Doc
2. Click **Share**
3. Paste the service account email
4. Set permissions and share

### Google Drive folders

Share an entire folder to give access to all files within:

1. Right-click the folder in Drive
2. Select **Share**
3. Paste the service account email
4. Set permissions

All files in the folder will be accessible.

---

## Capabilities

| Capability | Description |
|------------|-------------|
| `google-sa.files` | General service account access |

Service accounts access whatever you've shared with them — no additional scope configuration needed.

---

## Security

| Feature | Benefit |
|---------|---------|
| **You control access** | Only shared resources are accessible |
| **Auditable** | See who shared what in Google's sharing UI |
| **Revocable** | Remove the email from sharing to revoke access |
| **Isolated** | Each workspace gets its own service account |

The service account can **only** access files explicitly shared with it. It cannot browse your Drive or access anything you haven't shared.

---

## Using in apps

Declare the requirement in your app:

```yaml
# inf.yml
credentials:
  - key: google-sa.files
    description: Access team spreadsheets
```

The REST API uses `provider: "google-sa"` and `type: "service_account"` for connect calls. The web app's detail page slug is `google-sa` (separate from Google OAuth's `google` slug and GCP WIF's `gcp` slug).

If your app previously declared `google.sa` or `gcp.sa`, update the key to `google-sa.files`. Workspaces that connected under the older provider names already have `google-sa` connections, so no reconnect is needed.

At runtime, your app receives:

```bash
GOOGLE_ACCESS_TOKEN=ya29...
GOOGLE_SERVICE_ACCOUNT_EMAIL=agent-yourteam@...
GOOGLE_TOKEN_EXPIRES_IN=3600
```

### Example: Read a Google Sheet

```python
import gspread
from google.oauth2.credentials import Credentials

creds = Credentials(token=os.environ["GOOGLE_ACCESS_TOKEN"])
client = gspread.authorize(creds)

# Open by URL (must be shared with the service account)
sheet = client.open_by_url("https://docs.google.com/spreadsheets/d/...")
data = sheet.sheet1.get_all_records()
```

---

## Troubleshooting

### "Permission denied" on a shared resource

- Verify the service account email is in the resource's sharing settings
- Check the permission level (Viewer vs Editor)
- For Drive, make sure the file isn't restricted to organization members only

### "File not found"

- Double-check the file/sheet URL or ID
- Confirm the file is shared with the service account email
- Organization files may have sharing restrictions — check with your admin

### Service account email not showing

- Go to **vaults → credentials** and look for the connected Google Service Account
- The email is displayed in the credential card

---

## Service Account vs OAuth

| Feature | Service Account | OAuth |
|---------|-----------------|-------|
| Setup | Click connect, get email | Sign in with Google |
| Access model | Share files with email | Personal account permissions |
| Best for | Shared resources | Personal data (Gmail, Calendar) |
| User interaction | None after setup | OAuth consent flow |

Use **Service Account** for shared resources. Use **[Google OAuth](/docs/credentials/google-oauth)** for personal services like Gmail and Calendar.

---

## Next

→ [Google OAuth](/docs/credentials/google-oauth)