Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 102 lines 9.06 KB
Rendered Raw
1 ## How do I set up custom Google OAuth credentials for Google Super?
2
3 Use your own Google OAuth app when you need scopes that Composio's managed Google Super app doesn't have approved, your app's name on Google's consent screen, or a dedicated API quota. One OAuth client in one Google Cloud project can serve Google Super and the single-product Google toolkits.
4
5 ### Create the Google OAuth app
6
7 1. Open the [Google Cloud console](https://console.cloud.google.com/) and select the project that will own the OAuth app, or create one.
8
9 ![Google Cloud project picker with the OAuth app's project selected](/images/toolkits/shared/hjaj4jg5CtBRolXXYddY8NDXCes.webp)
10
11 2. Go to **APIs & Services** → **Library** and enable the API for each Google product your tools use. There is no separate Google Super API. The default scopes cover the **Gmail API**, **Google Drive API**, **Google Docs API**, **Google Sheets API**, **Google Slides API**, **Google Calendar API**, **Google Tasks API**, **People API** (contacts), **Photos Library API**, **Google Analytics** APIs, and **Google Ads API**. If an API page shows **Manage**, it's already enabled. Enabling an API needs project permissions; ask your project admin if you can't.
12
13 ![Google Drive API page in the Google Cloud API Library with the Enable button](/images/toolkits/shared/VNt0egQy2o9O5i6LMd4JFpNcmAU.webp)
14
15 3. Go to **Google Auth Platform** → **Branding**. If you see **Get started**, enter the app name, user support email, and developer contact email, then save.
16
17 ![Google Auth Platform Branding page with the app name and user support email fields](/images/toolkits/shared/x4VkWS3iceKKFGyjlFN1THrtTRQ.webp)
18
19 4. Under **Audience**, choose the user type. **Internal** limits sign-in to accounts in your Google Workspace organization. **External** allows any Google account. An External app starts in **Testing**; add every account that will connect under **Test users**.
20
21 ![Google Auth Platform Audience page showing Testing status, the External user type, and Test users](/images/toolkits/shared/Jttbz3Cm6xJFWNlukXLGTxWjf6c.webp)
22
23 5. Under **Data Access**, click **Add or remove scopes** and add the scopes your auth config will request (see **Scopes** below). Paste any scope missing from the list under **Manually add scopes** and click **Add to table**. Click **Update**, then **Save**.
24
25 ![Data Access scope picker with the drive.metadata.readonly scope selected](/images/toolkits/shared/ch2L6hWRPSOigltUpRF7r9hyA.webp)
26
27 6. Under **Clients**, click **Create client**. Set **Application type** to **Web application**, name the client, and add this URI under **Authorized redirect URIs**:
28
29 ```
30 https://backend.composio.dev/api/v1/auth-apps/add
31 ```
32
33 It must exactly match the `oauth_redirect_uri` field of your Composio auth config.
34
35 ![Create OAuth client ID form with Web application selected](/images/toolkits/shared/sA0bvCBPtMCWw8lqecCrx76Dyc.webp)
36
37 ![Create OAuth client ID form with the Composio redirect URI under Authorized redirect URIs](/images/toolkits/shared/jDTS80dlfwHF6u1WAQhBdnjTrI.webp)
38
39 7. Click **Create**. Copy the **Client ID** and **Client secret** before you close the dialog, and store the secret privately.
40
41 ![OAuth client created dialog with the Client ID and Client secret](/images/toolkits/shared/YdKWAswsL2nVXnSbA4zgBUDmwA.webp)
42
43 ### Create the auth config in Composio
44
45 1. In the [Composio dashboard](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs&utm_medium=content&utm_campaign=toolkits-googlesuper), go to **Auth Configs** → **Create** and select **Google Super**. Enter a config name and click **Next**.
46
47 ![Composio Auth Configs page with the Create button](/images/toolkits/shared/DUtMN0UWIU2kEqnvS5DvD7qhWU.webp)
48
49 ![Create Auth Config dialog with Google Super in the toolkit search results](/images/toolkits/googlesuper/composio-select-toolkit.webp)
50
51 ![Config Name field for the new Google Super auth config](/images/toolkits/googlesuper/composio-config-name.webp)
52
53 2. Choose **OAuth 2.0** and **Your Own Credentials**. Paste the **Client ID** and **Client secret**, and leave **Redirect URI** set to `https://backend.composio.dev/api/v1/auth-apps/add`.
54
55 ![Google Super auth config form with Client ID, Client secret, the Composio redirect URI, and a selected scope](/images/toolkits/googlesuper/composio-auth-config-form.webp)
56
57 3. Choose the scopes your tools need, matching the ones you added under **Data Access**, then click **Create Auth Config**.
58 4. Click **Connect Account**, sign in with a Google account that can use the app (a test user while the app is in **Testing**), and approve the consent screen. Under **Accounts**, confirm the connection shows **Active**. The auth config's **Enabled** label doesn't mean an account is connected.
59
60 ![Google's unverified-app notice for an app in Testing](/images/toolkits/shared/M0mS4XrLbK5mU52ry578MBa7M.webp)
61
62 ![Google consent screen for the Google Super connection](/images/toolkits/googlesuper/google-consent-screen.webp)
63
64 ![Google Super auth config details with an Active connected account](/images/toolkits/googlesuper/composio-connected-account-active.webp)
65
66 For the general flow, see [custom auth configs](/docs/auth-configuration/custom-auth-configs).
67
68 To add another Google toolkit later, enable its API in the same project and reuse this OAuth client in a new auth config.
69
70 ### Scopes
71
72 The default Google Super auth config requests broad scopes across products: `https://mail.google.com/`, `drive`, `documents`, `spreadsheets`, `presentations`, `calendar`, `tasks`, `contacts.readonly`, `analytics`, `analytics.readonly`, `adwords`, the Photos `appcreateddata` read and edit scopes, `userinfo.email`, and `userinfo.profile`. Remove the ones for products you don't use, and prefer narrower scopes where they cover your tools. For example, listing Drive file metadata only needs `drive.metadata.readonly`. See Google's [OAuth 2.0 scope list](https://developers.google.com/identity/protocols/oauth2/scopes).
73
74 Short scope names on this page leave out the `https://www.googleapis.com/auth/` prefix. When you paste a scope under **Manually add scopes**, use the full URL, for example `https://www.googleapis.com/auth/userinfo.email`. Scopes already written as a full URL, such as `https://mail.google.com/`, go in as shown.
75
76 If you change the scopes later, reconnect the account so the user grants the new access.
77
78 ### Testing, publishing, and verification
79
80 - While an External app is in **Testing**, only test users can connect, and Google can show them an unverified-app notice. Google generally expires their authorizations after seven days, so they need to reconnect.
81 - To let any Google account connect, publish the app under **Audience**. Publishing doesn't verify the app.
82 - Public apps that request sensitive or restricted scopes generally need Google's OAuth verification. Check **Google Auth Platform** → **Verification Center**. Internal apps and apps in Testing can be exempt. See Google's [verification requirements](https://developers.google.com/identity/protocols/oauth2/production-readiness/overview).
83 - Several default scopes, including `https://mail.google.com/` and `drive`, are restricted. A public app that requests them needs restricted-scope verification, which can include a security assessment if your servers store or transmit that data.
84 - If Google blocks sign-in, check the app's audience, the test user list, the requested scopes, and your Workspace admin's app access policy.
85
86 ## Why am I seeing "App is blocked" when connecting Google Super?
87
88 Google can block consent when the OAuth client requests scopes that Google hasn't approved for that client. Follow [Google scope approvals and blocked-app troubleshooting](/docs/authentication/controlling-scopes#google-scope-approvals) to check the auth config and requested scopes. Toolkit defaults and scope recommendations don't establish the managed app's approved scopes.
89
90 If a required scope isn't approved for the managed app, use your own Google OAuth app with the required verification and reconnect through a custom auth config. See [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) and the setup steps above.
91
92 ## Why am I getting the "API has not been used in project" error?
93
94 When using custom OAuth credentials, the required Google API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry.
95
96 ## Why am I getting "Error 400: invalid_scope"?
97
98 The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
99
100 ## Why does the OAuth consent screen show "Composio" instead of my app?
101
102 By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).