Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Connect your users to Google Workspace services including Gmail, Google Calendar, Google Drive, and Google Sheets.
PropertyValue
Provider IDgoogle
PKCESupported
Token refreshAutomatic (refresh token reused)
Access token lifetime~1 hour
Redirect URIShown in Developer Portal

​
Step 1: Create a Google Cloud Project

1

Go to Google Cloud Console

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

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.
3

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

1

Open Clients page

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

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: Your application name
  • User support email: Your email
  • Authorized domains: Your domain
  • Developer contact: Your email
Click through the remaining steps and Save.
3

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
4

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
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

1

Open the Developer Portal

Go to portal.alterauth.com and navigate to your app.
2

Add Google provider

Go to OAuth Providers > Add Provider > Google.
3

Enter credentials

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

Select scopes

Choose the scopes your app needs. See the Available Scopes section below.
5

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 AlterVault, HttpMethod

async with AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
) as vault:
    # Use the grant_id returned by Alter Connect
    response = await vault.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)

ScopeDescription
openidAuthenticate with OpenID Connect
profileView basic profile info
emailView email address

​
Gmail

ScopeDescription
https://www.googleapis.com/auth/gmail.readonlyRead email messages and settings
https://www.googleapis.com/auth/gmail.sendSend email on user’s behalf
https://www.googleapis.com/auth/gmail.composeManage drafts and send emails
https://www.googleapis.com/auth/gmail.modifyRead, compose, send, and delete email

​
Google Calendar

ScopeDescription
https://www.googleapis.com/auth/calendar.readonlyView calendars
https://www.googleapis.com/auth/calendar.eventsView and edit calendar events

​
Google Drive

ScopeDescription
https://www.googleapis.com/auth/drive.readonlyView Drive files
https://www.googleapis.com/auth/drive.fileManage files opened with this app
https://www.googleapis.com/auth/driveFull Drive access (read, edit, create, delete)
Request the minimum scopes your app needs. You can always add more later. Users are more likely to authorize apps that request fewer permissions.

​
Common API Endpoints

Use CaseMethodURL
List calendar eventsGEThttps://www.googleapis.com/calendar/v3/calendars/primary/events
List Gmail messagesGEThttps://www.googleapis.com/gmail/v1/users/me/messages
Send emailPOSThttps://www.googleapis.com/gmail/v1/users/me/messages/send
List Drive filesGEThttps://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.