Guide

Create Auth Config - Gmail

Overview

Composio provides pre-configured OAuth 2.0 authentication for Gmail, allowing your AI agents to integrate with Gmail's email, search, and productivity features across 62 available tools. By using Composio's managed credentials, you leverage Google's standard OAuth flow with pre-approved scopes, eliminating the complexity of registering your own OAuth app with Google. This is the fastest path to production-ready Gmail integration. You can switch to custom OAuth credentials later if your use case requires additional scopes or custom branding.

Before you begin

  • Active Composio account with dashboard access (dashboard.composio.dev)
  • User role with permission to create auth configurations in your workspace
  • No prior Gmail OAuth setup required — Composio's managed app is ready to use

Step by step

1
ClickAuth Configs

Navigate to the Auth Configs section of the Composio dashboard by clicking the 'Auth Configs' link in the sidebar. This page displays all currently configured authentication methods for your workspace.

Step 1
2
ClickCreate Auth Config

Click the 'Create Auth Config' button to initiate a new authentication configuration. This opens a wizard to select and configure a toolkit.

Step 2
3
TypeSearch toolkits...

Type 'Gmail' in the search box labeled 'Search toolkits...' to filter the list of available toolkits. This narrows the options to email-related integrations.

Tip. You can search by partial name — typing 'mail' will also return Gmail results.
4
ClickGGmailOAuth 2.0

Click on 'GGmailOAuth 2.0' from the search results to select Gmail as your authentication toolkit. This selection indicates you want to configure OAuth 2.0 access to Gmail.

Step 4
5
ClickNext

Click the 'Next' button to proceed to the credentials configuration screen. This advances the wizard to the step where you choose between managed and custom OAuth credentials.

Step 5
6
ClickGet started quickly with Composio's secure defaults. You can switch to your own credentials anytime.

Review the option to use Composio's secure defaults, which displays messaging about getting started quickly with managed credentials. You can switch to custom credentials later if needed. This informs you of the benefits of Composio's pre-approved OAuth app.

Tip. Composio's managed app is recommended for most use cases because it eliminates OAuth app registration and comes with Google-approved scopes.
Step 6
7
ClickComposio ManagedRecommendedGet started quickly with Composio's secure defaults. You can switch to your own credentials anytime.

Click the 'Composio Managed' radio button to confirm you want to use Composio's pre-configured OAuth credentials. This selection means your agents will use Composio's registered OAuth app with Google, not a custom app you manage.

Step 7
8
ClickCreate Auth Config

Click the 'Create Auth Config' button to finalize the Gmail OAuth 2.0 configuration. This completes the setup and adds the configuration to your workspace's available auth methods.

Step 8
9
TypeSearch toolkits...

The wizard may return to a search or config selection screen. If you need to configure additional toolkits, type in the search box again; otherwise, navigate back to the Auth Configs page to confirm your Gmail configuration is listed and active.

Tip. If you've completed the Gmail setup and don't need additional configs, return to the Auth Configs page using the sidebar link to verify the new configuration appears in the list.

Confirm it worked

  1. 1You see the Auth Configs page listing all active authentication configurations
  2. 2A new Gmail OAuth 2.0 configuration appears in the Auth Configs list with 'Active' or 'Ready' status
  3. 3The configuration shows 'Composio Managed' label, confirming you're using Composio's pre-approved OAuth app

Common issues

Keep reading