Salesforce Connected App Setup

To fetch reports via the API, ReportZen needs one read-only "External Client Application" in your Salesforce org. This page is written so you can hand it directly to your IT team or Salesforce administrator.
Admin time: about 10 minutes (plus up to 10 minutes for settings to propagate) / Required permission: System Administrator

Security notes for your administrator

The only OAuth scope requested is "Manage user data via APIs (api)". There is no persistent connection to, and no data transfer to, any external service — the user's own spreadsheet pulls data directly from your org.
Access is identical to the view permission of the single user set as the "Run As" user. If you set the requesting user there, the app can never see more than that user already sees on screen.
The credentials are never written into code. They are stored only in the user's private Google account property store — invisible to anyone the spreadsheet is shared with, and to the developer.

AAdministrator steps (about 10 min)

A-1. Create a new External Client Application

Setup → Quick Find: App Manager
Click "New External Client App" in the top right

Newer Salesforce UIs no longer show the classic "New Connected App" button. "New External Client App" is its successor with equivalent settings.

Fill in the basics:
- App name: anything, e.g. SF_Report_Export
- API name: letters, digits and underscores only
- Contact email: the administrator's email / Distribution state: Local

If the app name contains non-ASCII characters, the auto-filled API name becomes invalid and saving fails. Correct the API name by hand.

A-2. OAuth settings

Check "Enable OAuth"
Callback URL: https://localhost (not used, but the field is required)
OAuth scopes: move only "Manage user data via APIs (api)" to the selected list. Do not add full or web

Double-check the callback URL — accidental double pastes (https://localhosthttps://localhost) are a common mistake.

A-3. Enable the Client Credentials Flow (the step most often missed)

Scroll down on the same screen → under "OAuth flows and external client app enhancements", check "Enable Client Credentials Flow"
In the "Run As" field that appears, enter the Salesforce username of the user the app should run as
Save

The "Run As" value is the Salesforce username, not the email address (they can look identical but differ). The safe way: Setup → Users → copy the value from the "Username" column.

To fix anything after saving, always edit the existing app. Creating it again via "New" fails with an "already exists" error. Existing apps are listed under Quick Find: "External Client App Manager", not under App Manager.

A-4. Issue and hand over the credentials

Open the created app's "Settings" tab → OAuth settings → click "Consumer Key and Secret" (a verification code is sent to the operator's email)
Hand the displayed Consumer Key and Consumer Secret to the requesting user through a secure channel (a password manager share, etc.). Avoid plain chat or email

A-5. One more thing to pass along

Setup → Quick Find: "My Domain" → copy the "Current My Domain URL" value (the xxxx.my.salesforce.com form)

The xxxx.lightning.force.com address from the browser bar does not work for API calls. ReportZen auto-corrects common variants during setup, but the my.salesforce.com form is the reliable one.

That's everything on the administrator side. Thank you!

BUser steps in the add-on (about 5 min)

Open a Google Sheet → Extensions → ReportZen → Setup (connection info), and enter the URL from A-5 and the key/secret from A-4
Run Test connection and confirm it succeeds
Run Create report list sheet → in the created sheet, enter the target report ID (the string starting with 00O in the report's URL)
Run Refresh all reports → the Result column shows ✅ with the row count. The free plan fetches up to 2,000 rows; Enter license key (unlock full export) removes the cap and unlocks Enable daily auto refresh

Report requirements: the report format must be tabular, and the report must include a record ID column (e.g. Account ID).

CError quick reference

Error	Cause	Fix
"The API name can only contain…"	Non-ASCII app name auto-filled the API name	Correct the API name by hand (A-1)
"Enter a valid Run As user"	Run As is empty, or an email address was entered	Enter the username (A-3)
"already exists"	Recreated via "New" instead of editing	Edit the existing app (A-3)
SyntaxError: Unexpected token '<' … is not valid JSON	URL is in the lightning.force.com form	Use the my.salesforce.com form (A-5)
invalid_grant: no client credentials user enabled	Flow checkbox or Run As user not saved	Redo A-3 and save
Authentication keeps failing	Settings not yet propagated (up to 10 min)	Wait a few minutes and retry

These steps were verified end-to-end on a Salesforce Developer Edition org. Questions: see Support.