Google

Overview

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

Property	Value
Provider ID	google
Category	Productivity
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 the Google Auth Platform Clients page 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: The operator’s support email
• Authorized domains: The application’s domain
• Developer contact: The operator’s contact 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 your identity with OpenID Connect
profile	View your basic profile information
email	View your email address

Gmail

Scope	Description
https://www.googleapis.com/auth/gmail.readonly	View your email messages and settings
https://www.googleapis.com/auth/gmail.send	Send email on your behalf
https://www.googleapis.com/auth/gmail.compose	Manage drafts and send emails
https://www.googleapis.com/auth/gmail.modify	Read, compose, send, and permanently delete all your email from Gmail

Google Calendar

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

Google Drive

Scope	Description
https://www.googleapis.com/auth/drive.readonly	View your Google Drive files
https://www.googleapis.com/auth/drive.file	View and manage Google Drive files that you have opened with this app
https://www.googleapis.com/auth/drive	See, edit, create, and delete all of your Google Drive files

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.
• See the Google OAuth 2.0 overview and web-server flow guide for details.

Policy-cataloged operations

Alter policy rules can target these attested operations and families for operation-level and parameter-aware controls.

Operation ID	Families	Method	Provider path
gmail.users.messages.send	send	POST	/gmail/v1/users/{userId}/messages/send
gmail.users.drafts.send	send	POST	/gmail/v1/users/{userId}/drafts/send
gmail.users.messages.list	read	GET	/gmail/v1/users/{userId}/messages
gmail.users.messages.get	read	GET	/gmail/v1/users/{userId}/messages/{id}
gmail.users.messages.delete	delete	DELETE	/gmail/v1/users/{userId}/messages/{id}
gmail.users.messages.trash	write	POST	/gmail/v1/users/{userId}/messages/{id}/trash
gmail.users.drafts.create	write	POST	/gmail/v1/users/{userId}/drafts
gmail.users.drafts.list	read	GET	/gmail/v1/users/{userId}/drafts
gmail.users.labels.list	read	GET	/gmail/v1/users/{userId}/labels
gmail.users.getProfile	read	GET	/gmail/v1/users/{userId}/profile