import { Tabs, Callout, Steps } from "nextra/components";

# Google

The Google auth provider enables tools and agents to call Google/Google Workspace APIs on behalf of a user.

<Callout>
  Want to quickly get started with Google services in your agent or AI app? The
  pre-built [Arcade Gmail MCP Server](/resources/integrations/productivity/gmail) is what you
  want!
</Callout>

### What's documented here

This page describes how to use and configure Google auth with Arcade.

This auth provider is used by:

- The [Arcade Gmail MCP Server](/resources/integrations/productivity/gmail), which provides pre-built tools for interacting with Google services
- Your [app code](#using-google-auth-in-app-code) that needs to call Google APIs
- Or, your [custom tools](#using-google-auth-in-custom-tools) that need to call Google APIs

## Configuring Google auth

You can either use Arcade's default Google OAuth provider (fastest way to get started), or configure your own Google OAuth provider for production.

## Arcade's default Google OAuth provider

Arcade provides a default Google OAuth provider (the Arcade-managed Google app) that you can use to quickly get started. This provider supports a fixed set of scopes and is shared across all Arcade users.

### Supported scopes

The default Arcade Google OAuth provider supports the following scopes:

- `https://www.googleapis.com/auth/calendar.readonly`
- `https://www.googleapis.com/auth/calendar.events`
- `https://www.googleapis.com/auth/calendar.events.readonly`
- `https://www.googleapis.com/auth/calendar.settings.readonly`
- `https://www.googleapis.com/auth/contacts`
- `https://www.googleapis.com/auth/contacts.readonly`
- `https://www.googleapis.com/auth/drive.file`
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/gmail.compose`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.labels`
- `https://www.googleapis.com/auth/userinfo.email`
- `https://www.googleapis.com/auth/userinfo.profile`
- `openid`

<Callout type="warning">
  If you try to use a scope that is not in this list with the default Arcade Google provider, you will get a `400 invalid authorization challenge: requesting unsupported scopes` error. For example, scopes like `https://www.googleapis.com/auth/drive.readonly` are not supported.

  To use scopes beyond this list, you must create your own Google OAuth provider (see below).
</Callout>

### Limitations

The default provider has some limitations:

- **Fixed scope list**: You can only use the scopes listed above
- **Shared rate limits**: All Arcade users share the same rate limits
- **Arcade branding**: Your users will see "Arcade" as the requesting application

<Callout type="info">
  For production use, we strongly recommend creating your own Google OAuth provider. This gives you:

  - Full control over which scopes to request
  - Dedicated rate limits for your application
  - Your own branding in the OAuth consent screen
  - Better security and compliance with your organization's policies
</Callout>

## Configuring your own Google OAuth provider

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own Google app credentials. This way, your users will see your application's name requesting permission.


Before showing how to configure your Google app credentials, let's go through the steps to create a Google app.

### Create a Google app

- Follow Google's guide to [setting up OAuth credentials](https://support.google.com/cloud/answer/6158849?hl=en)
- Choose the [scopes](https://developers.google.com/identity/protocols/oauth2/scopes) (permissions) you need for your app
- At a minimum, you must enable these scopes:

  - `https://www.googleapis.com/auth/userinfo.email`
  - `https://www.googleapis.com/auth/userinfo.profile`
- Add the redirect URL generated by Arcade (see below) to the Authorized redirect URIs list
- Copy the client ID and client secret to use below

Next, add the Google app to Arcade.

### Setting up your Google OAuth provider in Arcade


<Tabs items={["Dashboard GUI"]}>
<Tabs.Tab>

### Configure Google Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **Included Providers** tab at the top.
- In the **Provider** dropdown, select **Google**.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "my-google-provider").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your Google app.
- Note the **Redirect URL** generated by Arcade. This must be added to your Google app's Authorized redirect URIs list.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

When you use tools that require Google auth using your Arcade account credentials, Arcade will automatically use this Google OAuth provider. If you have multiple Google providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

</Tabs.Tab>
</Tabs>

## Using Google auth in app code

Use the Google auth provider in your own agents and AI apps to get a user token for Google APIs. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for Google APIs:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {22-26}
from arcadepy import Arcade
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable

user_id = "{arcade_user_id}"

"""
In this example, we will use Arcade to authenticate with Google and
retrieve Gmail messages.

There is a tool for that in the Arcade SDK, which simplifies the process for
you to retrieve email messages either through our Python or JavaScript
SDKs or via LLM tool calling.

Below we are just showing how to use Arcade as an auth provider, if you ever
need to.
"""

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="google",
    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token

if not token:
    raise ValueError("No token found in auth response")

credentials = Credentials(token)
gmail = build("gmail", "v1", credentials=credentials)

email_messages = (
    gmail.users().messages().list(userId="me").execute().get("messages", [])
)

print(email_messages)
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {20-22}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable

const userId = "{arcade_user_id}";

/*
In this example, we will use Arcade to authenticate with Google and
retrieve Gmail messages.

There is a tool for that in the Arcade SDK, which simplifies the process for
you to retrieve email messages either through our Python or JavaScript
SDKs or via LLM tool calling.

Below we are just showing how to use Arcade as an auth provider, if you ever
need to.
*/

// Start the authorization process
let authResponse = await client.auth.start(userId, "google", {
  scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
});

if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}

// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);

if (!authResponse.context.token) {
  throw new Error("No token found in auth response");
}

const token = authResponse.context.token;

// Use the Google Gmail API
const response = await fetch(
  "https://gmail.googleapis.com/gmail/v1/users/me/messages",
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const data = await response.json();
const emailMessages = data.messages || [];

// Return a list of ids and thread ids
console.log(emailMessages);
```

</Tabs.Tab>

</Tabs>

## Using Google auth in custom tools

You can use the pre-built Arcade Google MCP Servers, like [Arcade Gmail MCP Server](/resources/integrations/productivity/gmail), to quickly build agents and AI apps that interact with Google services like Gmail, Calendar, Drive, and more.

If the pre-built tools in the Google MCP Servers don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with Google APIs.

Use the `Google()` auth class to specify that a tool requires authorization with Google. The `context.authorization.token` field will be automatically populated with the user's Google token:

```python {3-4,10-14,26}
from typing import Annotated

from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Google

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build


@tool(
    requires_auth=Google(
        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
    )
)
async def list_emails(
    context: ToolContext,
    subject: Annotated[str, "The subject of the email"],
    body: Annotated[str, "The body of the email"],
    recipient: Annotated[str, "The recipient of the email"],
) -> Annotated[str, "A confirmation message with the sent email ID and URL"]:
    """
    Send an email using the Gmail API.
    """
    if not context.authorization or not context.authorization.token:
        raise ValueError("No token found in context")

    credentials = Credentials(context.authorization.token)
    gmail = build("gmail", "v1", credentials=credentials)

    email_messages = (
        gmail.users().messages().list(userId="me").execute().get("messages", [])
    )

    return email_messages
```