Skip to content
SheetForge

Google Sheets Setup — Service Account & JSON Key

SheetForge reads Google Sheets in two modes.

  • ExportUrl needs no credentials: share the sheet by link, register each tab's #gid= value, and import. It is read-only.
  • SheetsApi authenticates as a Google service account and unlocks everything else: private sheets, write-back (reflect), and Push.

This page walks through SheetsApi setup end to end: creating the service account, downloading its JSON key, sharing your spreadsheet with it, and pointing SheetForge at the key. No prior Google Cloud experience is assumed. Every step happens in a web browser and costs nothing.

The whole flow:

  1. Create a Google Cloud project.
  2. Enable the Google Sheets API in it.
  3. Create a service account.
  4. Download the account's JSON key.
  5. Share your spreadsheet with the account's e-mail address.
  6. Point SheetForge at the key.

1. Create a Google Cloud project

  1. Open console.cloud.google.com and sign in with a Google account — it does not need to be the one that owns the spreadsheet. A personal account always works. Some company Google Workspace organizations disable service-account key downloads by policy, which makes step 4 fail with an organization-policy error (see "If something fails" below). On a first visit, accept the Terms of Service prompt to reach the console.
  2. In the top bar, click the project picker (the dropdown next to the Google Cloud logo), then New project.
  3. Enter any name (for example sheetforge-sheets) and click Create. Leave organization and location at their defaults.
  4. When the "project created" notification appears, select the new project in the picker. Everything below happens inside this project, so make sure it stays selected.

A project is just a container for API settings. Creating one is free, and the Sheets API usage in this guide has no cost.

2. Enable the Google Sheets API

  1. Open the left-hand menu (☰) and go to APIs & Services ▸ Library.
  2. Search for Google Sheets API and open the result.
  3. Click Enable. If the button reads Manage, the API is already enabled — nothing to do.

3. Create a service account

A service account is a machine identity with its own e-mail address. SheetForge signs in as this identity — your personal Google password is never involved.

  1. Go to APIs & Services ▸ Credentials.
  2. Click + Create credentials ▸ Service account.
  3. Enter a name (for example sheetforge-reader); the account ID fills in automatically. Click Create and continue.
  4. The "Grant this service account access to project" and "Grant users access" steps are optional — skip both and click Done. Access to your spreadsheet is granted by sharing the sheet (step 5), not by project roles.
  5. If the console suggests configuring an OAuth consent screen, ignore it — service accounts do not use one.

4. Download the JSON key

  1. Back on the Credentials page, click the service account you just created (under "Service accounts").
  2. Open the Keys tab.
  3. Click Add key ▸ Create new key, choose JSON, and click Create.
  4. The browser downloads a file named like sheetforge-sheets-1a2b3c.json. This is the only copy — Google does not keep it for re-download. If you lose it, delete the key in the Keys tab and create a new one.

Treat this file like a password:

  • Move it somewhere outside your Unity project and repository, for example C:/keys/sheetforge.json.
  • Never put it under Assets/ — everything there is committed with the project, and a stray reference (or a Resources/StreamingAssets folder) can carry it into a build.
  • If the key ever leaks, delete it in the Keys tab (this revokes it immediately) and create a new one.

5. Share the spreadsheet with the service account

The key alone grants nothing. The service account can only read sheets that were explicitly shared with it — exactly like a human collaborator.

  1. Open the downloaded JSON file in any text editor and copy the client_email value. It looks like sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com.
  2. Open your spreadsheet in Google Sheets and click Share.
  3. Paste the address and pick a role:
    • Viewer is enough for import.
    • Editor is required for write-back — authoring reflect and Push.
  4. Turn off "Notify people" (the address has no inbox) and confirm.
  5. If Google warns about sharing outside your organization, confirm — a service account belongs to no organization.

Skipping this step is the most common setup mistake — every request then fails with a permission error, no matter how correct the key is.

6. Point SheetForge at the key

  1. In your import settings asset, set the source to GoogleSheet and the access mode to SheetsApi.
  2. Fill spreadsheetId with the long ID from the sheet's URL: https://docs.google.com/spreadsheets/d/<this part>/edit.
  3. Tell SheetForge where the key file is, one of two ways:
    • Recommended — environment variable. Set SHEETFORGE_SHEETS_KEY to the absolute path of the JSON file. Each developer sets their own, no path ever enters the repo, and it takes precedence over the settings field.
      • On Windows: setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json" in a terminal, then restart Unity and Unity Hub (already-running processes keep their old environment).
      • On macOS/Linux: export it in your shell profile and start Unity from that shell, or use launchctl setenv on macOS.
    • Or — settings field. Put the path in serviceAccountKeyPath, pointing outside the repository.
  4. Press ↓ Pull from source in Tools ▸ SheetForge ▸ Data Studio. A successful report means the whole chain — project, API, account, sharing, key — is working.

If something fails

  • Permission error (PERMISSION_DENIED / 403): the sheet is not shared with the client_email address (step 5) — the ID points at a real spreadsheet the service account cannot see.
  • Requested entity was not found (404): spreadsheetId is wrong — copy exactly the segment between /d/ and /edit in the sheet's URL.
  • "Service account key creation is disabled" / organization policy error in step 4: your Google Workspace organization enforces iam.disableServiceAccountKeyCreation. Ask an administrator to allow key creation for this project, or create the project under a personal Google account. The spreadsheet can be shared with that project's service account no matter who owns the sheet.
  • "Google Sheets API has not been used in project … or it is disabled": the API is not enabled in the project that issued the key (step 2) — enable it there, not in some other project. A freshly enabled API can take a few minutes to propagate.
  • Key file not found: the path has a typo, or Unity was started before the environment variable existed — set the variable, then restart Unity and Unity Hub.
  • Key compromised or lost: delete it in the service account's Keys tab, create a new JSON key, and replace the file. Nothing else changes — the e-mail address and sheet sharing stay valid.