Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 04:45 UTC
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