Skip to main content
The Google Workspace integration lets users link their personal Google account to Aperium so agents can read and act on their email, files, documents, spreadsheets, slides, and calendar. Setup happens in two places: configure an OAuth client in Google Cloud, then paste the credentials into the Aperium admin onboarding flow or the Admin Console’s MCP Servers tab. Google Workspace is a layered connection: the admin configures the OAuth client once for the tenant, and each user links their own Google account on top of it. Agents act as the linked user, with that user’s own Google permissions.

​
What agents can do

Read

  • Gmail — search and read messages and threads, fetch attachment links
  • Calendar — search events, list calendars
  • Drive — search files, read file content and metadata
  • Sheets — read ranges and named ranges, sheet info, revision history
  • Docs — read documents
  • Slides — read slides and thumbnails

Write — approval-gated

  • Gmail — send, reply, create drafts, trash and restore messages (bulk trash up to 1,000 at once)
  • Calendar — create, update, and delete events
  • Drive — upload files, create folders, trash / restore / delete
  • Sheets — create spreadsheets, add sheets, append / update / clear ranges
  • Docs — create documents, insert and replace text
  • Slides — replace text, set element text, set speaker notes
Every write tool is approval-gated. When an agent proposes a write, Aperium pauses and shows the exact change for a human to approve before anything is sent to Google. Reads run without a prompt.

​
What you’ll need

  • A Google Cloud project. You can use an existing project or create a new one.
  • An admin account that can manage OAuth credentials and APIs in that project.
  • Your Aperium deployment URL (for example https://app.your-company.com).

​
Setup

1

Create or select a Google Cloud project

Open the Google Cloud Console and either pick an existing project or create a new one. Every step below applies to this project.
2

Enable the required Google APIs

From the left panel, open APIs & Services, go to Enabled APIs and services, and click + ENABLE APIS AND SERVICES. Search for and enable each of these:
  • Gmail API
  • Google Drive API
  • Google Docs API
  • Google Sheets API
  • Google Slides API
  • Google Calendar API
Without every API enabled, the parts of the integration that depend on it will fail when users try to use them.
3

Configure the OAuth consent screen

Under APIs & Services, select the OAuth consent screen tab.
  • If your Google Cloud account belongs to a Google Workspace organization and you only need to authorize users in that org, choose Internal for User Type.
  • Otherwise, choose External.
Fill in the required fields:
  • App name (for example Aperium).
  • User support email.
  • Developer contact email.
Click SAVE AND CONTINUE.
4

Add the OAuth scopes

On the Scopes step of the consent screen, click ADD OR REMOVE SCOPES and add every scope below. These are the scopes Aperium requests at consent time.Identity
  • openid
  • https://www.googleapis.com/auth/userinfo.email
  • https://www.googleapis.com/auth/userinfo.profile
Gmail
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.send
  • https://www.googleapis.com/auth/gmail.modify
Drive
  • https://www.googleapis.com/auth/drive.readonly
  • https://www.googleapis.com/auth/drive.file
Docs
  • https://www.googleapis.com/auth/documents.readonly
  • https://www.googleapis.com/auth/documents
Sheets
  • https://www.googleapis.com/auth/spreadsheets.readonly
  • https://www.googleapis.com/auth/spreadsheets
Slides
  • https://www.googleapis.com/auth/presentations.readonly
  • https://www.googleapis.com/auth/presentations
Calendar
  • https://www.googleapis.com/auth/calendar.readonly
  • https://www.googleapis.com/auth/calendar.events
Several of these are classified as sensitive or restricted scopes by Google. For unverified apps you can still proceed using test users (next step). For a production rollout, plan to submit the app for Google’s OAuth verification.Click SAVE AND CONTINUE.
5

Add test users (External user type only)

If you chose External in the consent screen step and the app is not yet verified, add a test user entry for every email address that should be allowed to complete the OAuth flow. Without this, only the developer account can connect.Click SAVE AND CONTINUE, review the summary, and click BACK TO DASHBOARD.
6

Create the OAuth client credentials

Open the Credentials tab and click + CREATE CREDENTIALS then OAuth client ID.

Creating an OAuth client ID from the Credentials tab in Google Cloud Console.

  • Application type: Web application.
  • Name: Anything that makes the client easy to find later (for example Aperium).
Authorized JavaScript origins. Add the origin of your Aperium deployment, with no trailing slash:
For local development, also add http://localhost:3000.Authorized redirect URIs. Add the Aperium OAuth callback path:
For local development, also add http://localhost:8080/api/v1/google/auth/callback.Click CREATE. Google shows the Client ID and Client secret. Copy both, or use Download JSON to save the credentials file.
7

Paste the credentials into Aperium

Open Aperium and go to either the admin onboarding flow (first sign-in) or the Admin Console’s MCP Servers tab (any time after). Open the Connect Aperium to Google Workspace form and fill in:
  • OAuth Client ID. The client ID from Google Cloud.
  • OAuth Client Secret. The client secret from Google Cloud.
  • Redirect URI. The same redirect URI you registered in Google Cloud (for example https://<your-aperium-domain>/api/v1/google/auth/callback).
Click Enable. Once saved, every user can link their personal Google account from the Integrations page.

The Connect Aperium to Google Workspace form in the admin onboarding flow.

​
What users see

After admin setup is complete, users land on the Connect your tools page (during onboarding) or the Integrations page (any time after). They click Link Account on the Google Workspace tile, are redirected to Google’s consent screen, review the scopes Aperium is asking for, and click Allow to finish linking.

​
Going to production

For a production rollout where users outside a Workspace organization need to sign in, submit the OAuth app for Google verification. Restricted and sensitive scopes such as gmail.modify and the Drive, Docs, Sheets, and Slides write scopes typically require Google verification before the consent screen will allow non-test users to proceed.