@devries-cameron20 / composio-1 / commits / 067776ce7
Fork 0

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

docs: distinguish Google scope requests from app approvals

Brendan O'Leary committed Nov 13, 2026 at 14:55 UTC 067776ce7a8f7950687fda8f4de78f39effdb8c2
3 files changed +18 -4
docs/content/docs/authentication/controlling-scopes.mdx
+14
@@ -24,6 +24,20 @@ Scope recommendations and grant-context APIs are experimental. Review the recomm
24
25 Toolkit auth details also expose `required_scopes` (Python) or `requiredScopes` (TypeScript): scopes the auth method always requests, regardless of tool-specific scopes. Auth fields expose `user_visible` or `userVisible` to indicate whether the hosted connection flow displays them. These fields may be absent when the API does not provide them.
26
27 +## Google scope approvals
28 +
29 +For [Gmail](/toolkits/gmail) and [Google Super](/toolkits/googlesuper), the toolkit's default `scopes` value describes the permissions to request. It doesn't list the scopes Google has approved for Composio's managed OAuth app. Scope recommendations identify permissions needed by tools, and `available_scopes` is a constraint you supply, not an approval list returned by Google.
30 +
31 +Confirm that the managed app supports your exact scope URLs with [Composio support](mailto:support@composio.dev) before relying on a different scope set. Setting `credentials.scopes` passes scopes to Composio's API; it doesn't verify the OAuth app with Google.
32 +
33 +If Google shows "This app is blocked" after you add scopes:
34 +
35 +1. Check which auth config your session uses and which scopes it requests.
36 +2. Remove the added scopes if your tools don't need them. If a required scope isn't approved for the managed app, use your own Google OAuth app and complete Google's required verification for that app and its requested scopes.
37 +3. [Reconnect the account](#update-scopes-on-an-existing-config) so the user grants the new scope set.
38 +
39 +With your own OAuth app, configure the scopes your tools need in the provider's portal and in your custom auth config. Google consent uses that app's identity; managed auth uses Composio's app identity. See [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) to choose an app and set up its credentials.
40 +
41 ## Set scopes with Composio managed auth
42
43 Pass a `scopes` field in `credentials` to override the defaults while still using Composio's managed OAuth app. Give scopes as a comma-separated string.
docs/content/toolkits/faq/gmail.md
+2 -2
@@ -4,9 +4,9 @@ For a step-by-step guide on creating and configuring your own Google OAuth crede
4
5 ## Why am I seeing "App is blocked" when connecting Gmail?
6
7 -The OAuth client is requesting scopes that Google hasn't verified for that client. This usually happens when you add extra scopes beyond the defaults.
7 +Google can block consent when the OAuth client requests scopes that Google hasn't approved for that client. This can happen after you add scopes beyond the defaults.
8
9 -Remove the additional scopes from your auth config, or create your own OAuth app and submit the scopes for verification. See [How to create OAuth2 credentials for Google Apps](https://composio.dev/auth/googleapps).
9 +Follow [Google scope approvals and blocked-app troubleshooting](/docs/authentication/controlling-scopes#google-scope-approvals). Toolkit defaults and scope recommendations don't establish the managed app's approved scopes. If you need your own OAuth app, see [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) and [Google OAuth setup](https://composio.dev/auth/googleapps).
10
11 ## Why am I getting "Gmail API has not been used in project" error?
12
docs/content/toolkits/faq/googlesuper.md
+2 -2
@@ -4,9 +4,9 @@ For a step-by-step guide on creating and configuring your own Google OAuth crede
4
5 ## Why am I seeing "App is blocked" when connecting Google Super?
6
7 -Google Super requires broad Google Workspace scopes for some cross-product workflows, and some of those scopes are not available on Composio-managed Google Super auth today. If users see Google's "App is blocked" or unverified-app screen with managed Google Super auth, use your own verified Google OAuth app and reconnect through a custom auth config.
7 +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.
8
9 -Composio is working on getting the managed Google Super app approved for the needed scopes, but until that is complete, custom Google OAuth is the workaround for production usage. See [How to create OAuth2 credentials for Google Apps](https://composio.dev/auth/googleapps).
9 +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 [Google OAuth setup](https://composio.dev/auth/googleapps).
10
11 ## Why am I getting the "API has not been used in project" error?
12