> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Google Workspace integration Connect a Google account so that your Agents and Flows can use Gmail, Google Docs, and Google Sheets through tools. Add the tools to an Agent or to a prompt step in a Flow. The connection form also offers Calendar and Drive access, but no Runtype tool uses it. You do not need to select Calendar or Drive. ## Before you begin Prepare the following items before you connect Google Workspace: * A Google Cloud project that you can configure. * The Google APIs for the services that you plan to use. * An OAuth 2.0 client ID and client secret for a Web application. ## Create an OAuth client To connect Google Workspace, use your own Google Cloud OAuth client. Follow these steps: 1. In the [Google Cloud Console](https://console.cloud.google.com/), create or select a project. 2. Enable the API for each service that you plan to select: Gmail API, Google Calendar API, Google Docs API, Google Sheets API, or Google Drive API. 3. Configure the **OAuth consent screen**. For a Google Workspace organization, select **Internal**. For other accounts, select **External** and add your account under **Test users**. 4. Create an OAuth 2.0 client of type **Web application**. 5. Add the Runtype redirect URI to **Authorized redirect URIs**. Use `https://api.runtype.com/v1/oauth/google/callback`. The connection form also shows this URI with a copy button. 6. Save the client ID and client secret. > **Note** > > External apps in **Testing** mode receive refresh tokens that expire after 7 days. To avoid > this limit, publish the app or use an Internal app. A published External app that requests > Gmail, Docs, or Sheets access must pass Google app verification. In a Google Workspace > organization, use an Internal app to skip verification. ## Connect Google Workspace In an organization, the Google connection is shared. Agents and Flows that any member runs act as the connected Google account. They send email from that account and read its inbox, Docs, and Sheets. We recommend that you connect a dedicated Google account for automation, not a personal account. For more information, see [What are Organizations?](/user-guide/settings/what-are-organizations). To connect Google Workspace after you create the client, follow these steps: 1. In Runtype, open **Settings > Integrations**. 2. In the **Google** card, go to **Connect a Google account**. 3. Select at least one service: **Gmail**, **Calendar**, **Docs**, **Sheets**, or **Drive**. Runtype requests only the scopes for the services that you select. 4. If the form shows **Use my own Google OAuth client**, select it. The **Client ID** and **Client secret** fields appear. 5. In **Client ID**, enter your Google Cloud OAuth client ID. 6. In **Client secret**, enter your Google Cloud OAuth client secret. 7. Click **Connect Google**. 8. In the Google consent popup, approve the requested permissions. 9. In the **Google** card, check that the connection lists every service that you selected. If a service is missing, follow the steps in [Add a service to a connection](#add-a-service-to-a-connection) and allow all requested permissions. Runtype exchanges the authorization code and stores the tokens server-side. The tokens do not pass through your browser. Runtype does not store your Google password. You can also connect Google from the tool picker. When you add a Google tool to an Agent or a prompt step and no account is connected, the tool picker shows a setup panel with the same fields and a **Connect Google** button. > **Warning** > > Google tools use one connected Google account. If you connect more than one account, every > Google tool call fails. Runtype has no option to remove a connection, so connect only one > Google account. ### Add a service to a connection To add a service to an existing connection, use **Connect another Google account** in the **Google** card. Select every service that you need, including the extra service. If you use your own OAuth client, enter the client ID and client secret again, as in [Connect Google Workspace](#connect-google-workspace). Sign in with the same Google account. Runtype updates the existing connection and does not create a second one. **Reconnect** does not add services, because it requests only the services that the connection already has. ## Automatic refresh and reconnection Runtype refreshes the access token before it expires. Google can revoke a refresh token if you remove the app from your Google Account or if the refresh token expires. If the connection shows **Needs reconnection**, follow these steps: 1. In Runtype, open **Settings > Integrations**. 2. On the connection marked **Needs reconnection**, click **Reconnect**. 3. In the Google consent popup, approve the requested permissions. **Reconnect** requests the services that the connection already has and reuses your OAuth client. If Runtype cannot reuse the client, it shows an error. In that case, reconnect from the Google setup panel in the tool picker and enter the client ID and client secret again. ## Available tools After you connect, you can add the following tools to Agents and to prompt steps in Flows. The tools act on the connected Google account. | Service | Tool | Required parameters | What it does | | ------------- | -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Gmail | `gmail_send` | `to`, `subject`, `body` | Sends an email right away. The body is HTML. Optional: `cc` and `bcc` as comma-separated addresses. | | Gmail | `gmail_search` | `query` | Searches with Gmail search operators and returns message IDs. Optional: `max_results`, from 1 to 100 (default 10). Use `gmail_read` for the content. | | Gmail | `gmail_read` | `message_id` | Reads one email by its message ID. | | Gmail | `gmail_create_draft` | `to`, `subject`, `body` | Creates a draft. The body is HTML. Drafts have no `cc` or `bcc`. | | Google Docs | `docs_create` | `title` | Creates an empty Google Doc. The tool ignores the `content` parameter. | | Google Docs | `docs_read` | `document_id` | Reads a Google Doc. The document ID is in the document URL. | | Google Docs | `docs_append` | `document_id`, `content` | Inserts text at the start of the document body, not at the end. | | Google Sheets | `sheets_read` | `spreadsheet_id`, `range` | Reads cells in an A1 range, such as `Sheet1!A1:D10`. The spreadsheet ID is in the spreadsheet URL. | | Google Sheets | `sheets_write` | `spreadsheet_id`, `range`, `values` | Overwrites the range with an array of rows. Google evaluates values as typed input, so formulas are calculated. | | Google Sheets | `sheets_create` | `title` | Creates a Google Sheet. Optional: `sheets`, a list of tab names to create. | > **Tip** > > `gmail_send` sends email without confirmation. To review each message first, turn on > [Tool approval](/user-guide/agents/creating-and-configuring-agents#safety) for `gmail_send` in > the Agent, or use `gmail_create_draft`. ## Permissions and scopes Select only the services that your Agent or Flow needs. Runtype requests only the scopes for the services that you select. The following list describes the access that each service grants: * **Gmail**: read, send, and modify email, and create drafts. * **Calendar**: read and manage calendar events. * **Docs**: create, read, and edit documents. * **Sheets**: read, write, and create spreadsheets. * **Drive**: access files that the integration creates. ## Troubleshooting The following table lists common errors and how to fix them. | Error | Cause | Fix | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `Google did not return a refresh token.` | Google did not issue a refresh token for this authorization. | Remove the app at [Google Account permissions](https://myaccount.google.com/permissions), then connect again. | | `This Google authorization link has expired. Please restart setup.` | You waited too long before you approved the consent popup. | Click **Connect Google** again. | | `Google authorization was denied.` | You canceled the Google consent screen. | Connect again and approve the requested permissions. | | `Google Workspace is not connected.` | No Google account is connected. | Connect a Google account in **Settings > Integrations**. | | `Your Google connection needs to be reauthorized.` | Google revoked the refresh token. | Click **Reconnect** on the connection. | | `Multiple google integrations installed` | More than one Google account is connected. | Google tools work with one connected account only. Runtype has no option to remove a connection, so contact Runtype support. | | `Google API error (403)` | The API is not enabled in your Google Cloud project, or the service was not granted. | Enable the matching API in the Google Cloud Console. If the connection does not list the service, connect again with that service selected. | ## Revoke Google access Runtype has no option to disconnect Google. To revoke access, remove the app from your Google Account: 1. Open [Google Account permissions](https://myaccount.google.com/permissions). 2. In **Third-party apps**, find the app name that you set on your OAuth consent screen. 3. Click **Remove access**. After you remove access, Google tools fail. The connection shows **Needs reconnection** the next time Runtype tries to refresh the token. ## Next steps * [Creating and configuring Agents](/user-guide/agents/creating-and-configuring-agents): add Google tools to an Agent. * [Using prompt steps](/user-guide/flows/using-prompt-steps): use Google tools in a Flow. * [What are Tools?](/user-guide/tools/what-are-tools): compare tool types. * [What are Organizations?](/user-guide/settings/what-are-organizations): learn which integrations members share.