Google

Overview

Connect your users to Google Workspace services including Gmail, Google Calendar, Google Drive, and Google Sheets.

Property	Value
Provider ID	google
PKCE	Supported
Token refresh	Automatic (refresh token reused)
Access token lifetime	~1 hour
Redirect URI	Shown in Developer Portal

Step 1: Create a Google Cloud Project

Go to Google Cloud Console

Navigate to console.cloud.google.com and sign in with your Google account.

Create or select a project

Click the project dropdown at the top and select New Project. Give it a name (e.g., “My App - Alter Integration”) and click Create.

Enable APIs

Go to APIs & Services > Library and enable the APIs you need:

• Gmail API - for email access
• Google Calendar API - for calendar access
• Google Drive API - for file access
• Google Sheets API - for spreadsheet access

Step 2: Create OAuth Credentials

Open Clients page

Go to the Google Auth Platform > Clients page and click Create Client.

Configure consent screen (first time only)

If prompted, configure the OAuth consent screen:

• User Type: External (unless you only need Google Workspace users)
• App name: The application name
• User support email: Your email
• Authorized domains: Your domain
• Developer contact: Your email

Click through the remaining steps and Save.

Create OAuth client ID

• Application type: Web application
• Name: e.g., “Alter Vault Integration”
• Authorized redirect URIs: Copy the Redirect URI from the Developer Portal
• Click Create

Download credentials immediately

Download and securely store the Client ID and Client Secret from the dialog. The secret is only shown once at creation time.

The Client ID looks like: 123456789-abcdefg.apps.googleusercontent.com

Warning

Never share the Client Secret publicly. Client secrets are only visible at creation time — download and store securely (e.g., in a secret manager) before closing the dialog. Only enter the secret in the Alter Vault Developer Portal.

Step 3: Add to Alter Vault

Open the Developer Portal

Go to portal.alterauth.com and navigate to the application.

Add Google provider

Go to OAuth Providers > Add Provider > Google.

Enter credentials

• Client ID: Paste your Google Client ID
• Client Secret: Paste your Google Client Secret

Select scopes

Choose the scopes the application needs. See the Available Scopes section below.

Save

Click Save. The provider is now active and ready to use.

Step 4: Test It

After a user connects via Alter Connect, use the returned grant_id to make API calls:

from alter_sdk import App, HttpMethod

async with App(
    api_key="alter_key_...",
    caller="my-agent",
) as alter_app:
    # Use the grant_id returned by Alter Connect
    response = await alter_app.request(
        HttpMethod.GET,
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        grant_id=grant_id,
        query_params={"maxResults": "5"},
    )
    events = response.json()
    print(f"Found {len(events.get('items', []))} events")

Available Scopes

Identity (included by default)

Scope	Description
openid	Authenticate with OpenID Connect
profile	View basic profile info
email	View email address

Gmail

Scope	Description
https://www.googleapis.com/auth/gmail.readonly	Read email messages and settings
https://www.googleapis.com/auth/gmail.send	Send email on user’s behalf
https://www.googleapis.com/auth/gmail.compose	Manage drafts and send emails
https://www.googleapis.com/auth/gmail.modify	Read, compose, send, and delete email

Google Calendar

Scope	Description
https://www.googleapis.com/auth/calendar.readonly	View calendars
https://www.googleapis.com/auth/calendar.events	View and edit calendar events

Google Drive

Scope	Description
https://www.googleapis.com/auth/drive.readonly	View Drive files
https://www.googleapis.com/auth/drive.file	Manage files opened with this app
https://www.googleapis.com/auth/drive	Full Drive access (read, edit, create, delete)

Tip

Request the minimum scopes the application needs. You can always add more later. Users are more likely to authorize apps that request fewer permissions.

Common API Endpoints

Use Case	Method	URL
List calendar events	GET	https://www.googleapis.com/calendar/v3/calendars/primary/events
List Gmail messages	GET	https://www.googleapis.com/gmail/v1/users/me/messages
Send email	POST	https://www.googleapis.com/gmail/v1/users/me/messages/send
List Drive files	GET	https://www.googleapis.com/drive/v3/files

Notes

• Google requires access_type=offline and prompt=consent to issue refresh tokens. Alter Vault handles this automatically.
• If requesting profile or email scopes, the openid scope is automatically included.
• Refresh tokens never expire unless the user revokes access or the token is inactive for 6 months.
• Google enforces a limit of ~50 refresh tokens per user per app. Alter Vault’s connection deduplication prevents hitting this limit.