Google APIs

Almost every Google API uses the same OAuth flow + scopes pattern. Once you've wired up auth, swapping Sheets for Calendar for Gmail is a one-line change to the scope list.

Step 1: Create the OAuth app

In the Google Cloud Console:

1. 1

   Create or pick a project

   Top bar → project dropdown → New project (or pick an existing one).

2. 2

   Enable the APIs you need

   APIs & Services → Library. Find your APIs (e.g., Google Sheets API, Google Calendar API) and click Enable on each.

3. 3

   Configure the OAuth consent screen

   APIs & Services → OAuth consent screen. Pick External (for any non-Workspace Google account) or Internal (Workspace-only).

   Add the scopes you'll request (see the next section). For sensitive scopes, Google requires verification before non-test users can sign in.

4. 4

   Create OAuth client credentials

   APIs & Services → Credentials → Create credentials → OAuth client ID → Web application.

   Authorised redirect URIs: add your FlareX app URL:

   https://<your-app>-<hex>.flarex.app/auth/google/callback
   

   Save. Copy the client ID and client secret.

Step 2: Add credentials to Secrets

GOOGLE_CLIENT_ID=...apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=https://my-app-abc123.flarex.app/auth/google/callback

Step 3: Pick scopes carefully

Step 4: Wire up the flow

Add Google OAuth using GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET,
GOOGLE_REDIRECT_URI from Secrets.

Scopes: openid, email, profile,
https://www.googleapis.com/auth/spreadsheets.readonly

Store access_token + refresh_token + token_expiry in the
google_tokens table keyed by user_id. Refresh transparently when expired.

FlareX writes the routes (see the OAuth doc for the structure).

Pattern 1: Read a Sheet

Add a /sheets/:id endpoint. Use the user's stored Google token to
fetch the entire sheet at id, return rows as an array of objects with
the first row as headers. Cache for 60s in Redis keyed by sheet id +
user id.

import { google } from 'googleapis';

const auth = new google.auth.OAuth2();
auth.setCredentials({ access_token: token, refresh_token: refreshToken });
const sheets = google.sheets({ version: 'v4', auth });

const res = await sheets.spreadsheets.values.get({
  spreadsheetId: id,
  range: 'A:Z',
});

Pattern 2: List upcoming Calendar events

Add a /calendar/upcoming endpoint. Return the next 10 events from the
user's primary calendar with summary, start, end, location.

const calendar = google.calendar({ version: 'v3', auth });
const res = await calendar.events.list({
  calendarId: 'primary',
  timeMin: new Date().toISOString(),
  maxResults: 10,
  singleEvents: true,
  orderBy: 'startTime',
});

Pattern 3: Service account (no per-user OAuth)

For server-to-server access — e.g., a dashboard reading your own Sheet — skip the user OAuth flow entirely. Use a service account:

1. 1

   Create a service account

   Cloud Console → IAM & Admin → Service Accounts → Create. Download the JSON key.

2. 2

   Share the resource with the service account email

   Copy the service account email (looks like …@…iam.gserviceaccount.com). Open your Sheet → Share → paste the email → grant Viewer.

3. 3

   Add the JSON key to Secrets

   GOOGLE_SERVICE_ACCOUNT_JSON = the entire contents of the downloaded JSON file (paste as multiline value).

4. 4

   Use it

   Use GOOGLE_SERVICE_ACCOUNT_JSON to authenticate as a service
   account. Read sheet "1abc…" and refresh every 5 minutes.
   

Service accounts don't need user consent — but they can only access resources explicitly shared with them. Cleaner for "platform reads from a fixed sheet" use cases; not appropriate for "user connects their Google account."

Common errors

What's next

• OAuth — the universal 3-legged flow
• 3rd-party APIs overview — retries, rate limits, caching
• Build a dashboard — common pattern for Google Sheets data