Google Integrations

The Google Sheets, Gmail, and Google Drive integrations connect to a Google account through OAuth. On self-hosted Skyvern this is off by default. Once you configure a Google OAuth client, users can connect their accounts from the Integrations page and the OAuth callback completes in your own UI.

1. Create a Google OAuth client

In the Google Cloud Console, select or create a project.
Enable the Google Sheets API, Google Drive API, and Gmail API for the project (APIs & Services → Library).
Configure the OAuth consent screen. External apps must add each user as a test user (or publish the app) before they can connect.
Create an OAuth client ID of type Web application (APIs & Services → Credentials → Create credentials).
Add your Skyvern UI’s callback URL to Authorized redirect URIs. The path is always /integrations/google/callback:
- Local: http://localhost:8080/integrations/google/callback
- Production: https://skyvern.your-company.com/integrations/google/callback
Copy the generated Client ID and Client secret.

2. Required scopes

Skyvern requests a scope profile for the integration the user connects.

Google Sheets

Scope	Purpose
`https://www.googleapis.com/auth/spreadsheets`	Read and write spreadsheet contents
`https://www.googleapis.com/auth/drive.file`	Access files the app creates or the user opens
`https://www.googleapis.com/auth/drive.metadata.readonly`	List and look up spreadsheets by name

Gmail

Scope	Purpose
`https://www.googleapis.com/auth/gmail.readonly`	Read messages for verification codes and magic links

Google Drive

Scope	Purpose
`https://www.googleapis.com/auth/drive`	Upload files to Drive, including existing folders selected by ID or URL

You don’t set these manually — Skyvern requests the appropriate profile automatically. If your consent screen restricts scopes, add the scopes above so users can grant them.

3. Configure the OAuth client in Skyvern (recommended)

First, enable encryption on the backend (.env or your deployment’s environment), then restart Skyvern:

.env

ENABLE_ENCRYPTION=true
ENCRYPTOR_AES_SECRET_KEY=<32-byte base64 key>

Then configure the client for your organization:

Open Settings → Google OAuth, or use the Google OAuth form at the top of Integrations.
Confirm that the read-only Callback URL matches the redirect URI you registered with Google.
Paste the Client ID and Client Secret from step 1.
Set Redirect Hosts to the hostname allowed for the OAuth redirect (hostname only, without a scheme or path).
Set App Origins to the origin allowed to finish the flow (scheme, host, and port when applicable).
Click Save Configuration.

Skyvern stores the OAuth client configuration AES-encrypted per organization. The client secret is never displayed again after you save it; leave the field blank when updating the other values to keep the existing secret.

4. Environment variables (alternative)

Operators who prefer environment configuration can set these values on the backend (.env or your deployment’s environment), then restart Skyvern. An organization-level configuration saved in Settings takes precedence over these environment values.

.env

# Enable encryption — OAuth refresh tokens are never stored in plaintext.
ENABLE_ENCRYPTION=true
ENCRYPTOR_AES_SECRET_KEY=<32-byte base64 key>

# Google OAuth client from step 1.
GOOGLE_OAUTH_CLIENT_ID=<your-client-id>.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=<your-client-secret>

# Hostname(s) allowed as the OAuth redirect_uri (host only, no scheme or path).
# Must match the host of the redirect URI you registered with Google.
GOOGLE_OAUTH_REDIRECT_HOSTS=skyvern.your-company.com

# App origin(s) allowed to receive the connected credential after callback
# (scheme + host + port). This is the origin your UI is served from.
GOOGLE_OAUTH_APP_ORIGINS=https://skyvern.your-company.com

Variable	Required	Description
`GOOGLE_OAUTH_CLIENT_ID`	Yes	Web-application client ID from Google Cloud.
`GOOGLE_OAUTH_CLIENT_SECRET`	Yes	Client secret paired with the client ID.
`GOOGLE_OAUTH_REDIRECT_HOSTS`	Yes	Comma-separated hostnames permitted as the `redirect_uri`. Non-loopback hosts must use HTTPS.
`GOOGLE_OAUTH_APP_ORIGINS`	Yes	Comma-separated origins (`scheme://host[:port]`) permitted to finish the flow. Empty rejects every connect attempt.
`ENABLE_ENCRYPTION`	Yes	Must be `true`; credentials are refused if encryption is off.

For local development, localhost is treated as a loopback host, so http://localhost:8080 works for both GOOGLE_OAUTH_REDIRECT_HOSTS (localhost) and GOOGLE_OAUTH_APP_ORIGINS (http://localhost:8080).

5. Verify

Restart the backend so the encryption or environment settings load.
Open the Skyvern UI and go to Integrations. Confirm that the Google Sheets, Gmail, and Google Drive cards each show a Connect button.
Click Connect on one of the cards and complete the Google consent screen. You land back on the Integrations page with the account listed under Connected Google Accounts.
Use the connected account in the corresponding Google Sheets, Gmail, or Google Drive workflow feature.

If Connect returns an error, double-check that the redirect URI registered with Google matches Redirect Hosts (or GOOGLE_OAUTH_REDIRECT_HOSTS), and that App Origins (or GOOGLE_OAUTH_APP_ORIGINS) contains the exact origin your UI runs on.

Getting Started

Core Features

Browser Automation

Agent Blocks

Handling Authentication

Optimization

Going to Production

Debugging

Self-Hosted Deployment

Google Integrations

1. Create a Google OAuth client

2. Required scopes

Google Sheets

Gmail

Google Drive

3. Configure the OAuth client in Skyvern (recommended)

4. Environment variables (alternative)

5. Verify

​1. Create a Google OAuth client

​2. Required scopes

​Google Sheets

​Gmail

​Google Drive

​3. Configure the OAuth client in Skyvern (recommended)

​4. Environment variables (alternative)

​5. Verify

1. Create a Google OAuth client

2. Required scopes

Google Sheets

Gmail

Google Drive

3. Configure the OAuth client in Skyvern (recommended)

4. Environment variables (alternative)

5. Verify