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: clarify Google scope approvals and blocked-app troubleshooting (DEVREL-189) (#5381)
> Written by an AI agent on behalf of Brendan. Brendan approved the approach and has not reviewed this diff yet. ## Summary Developers connecting Gmail or Google Super can mistake toolkit defaults or scope recommendations for Google-approved permissions. The FAQs also lacked a shared explanation of app ownership and scope approval, and Google Super's answer made an unverified claim that managed-app approval was in progress. Related: [DEVREL-189](https://linear.app/composio/issue/DEVREL-189). Designated PR reviewer: @jkomyno. ## Changes - Add a Google scope-approval section explaining default requests, tool recommendations, the caller-supplied `available_scopes` constraint, and SDK forwarding to Composio's API. - Add conditional blocked-app troubleshooting, reconnect guidance, consent-screen ownership, and a link to the managed-versus-custom auth guide. - Link the Gmail and Google Super FAQs to that section and replace the Google Super approval-progress claim with conditional guidance. | Reader question | Before | After | | --- | --- | --- | | Do defaults or recommendations prove Google approval? | No explicit distinction in the scope guide. | Explains the distinction and directs readers to support for the exact managed-app scope set. | | What should I check after Google blocks consent? | Separate FAQ answers and external setup links. | Shared steps to check the selected config, remove unnecessary additions or use a verified custom app, and reconnect. | ## Type of change - [ ] Bug fix - [ ] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? At head `067776ce7a8f7950687fda8f4de78f39effdb8c2`: - From `docs/`: `bun test tests/static/dashboard-links.test.ts`: 3 passed, 0 failed, exit 0. - `git diff --check origin/next...HEAD`: exit 0. - A dependency-free Python check resolved all 23 internal Markdown links and anchors across the three changed files and confirmed code fences are unchanged from `origin/next`. Source evidence: [TypeScript schema](https://github.com/ComposioHQ/composio/blob/067776ce7a8f7950687fda8f4de78f39effdb8c2/ts/packages/core/src/types/authConfigs.types.ts#L69-L82) accepts scope strings or arrays, [TypeScript create](https://github.com/ComposioHQ/composio/blob/067776ce7a8f7950687fda8f4de78f39effdb8c2/ts/packages/core/src/models/AuthConfigs.ts#L155-L170) forwards credentials, and [Python create](https://github.com/ComposioHQ/composio/blob/067776ce7a8f7950687fda8f4de78f39effdb8c2/python/composio/core/models/auth_configs.py#L45-L57) forwards the options. A prior research check executed that Python method against a recording stub and confirmed arbitrary scopes reach the API client unchanged. This does not establish backend handling or Google's actual grant. No dependencies were installed. Full site build, lint, and full-site link validation were not run under the shared-machine constraint. No new tests were added because the change is prose and links; existing link-policy tests and focused link checks cover the edited content. ## Screenshots (if applicable) Not applicable: content and links only; no layout changes. The table above compares the authored guidance. ## Checklist - [ ] I have read the Code of Conduct and this PR adheres to it - [ ] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the [third-party links policy](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md#third-party-links-in-docs) - [ ] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages ## Additional context Brendan explicitly approved keeping the managed-app approval inventory unpublished, documenting only SDK forwarding and conditional troubleshooting, and omitting CASA claims and assessment exemptions. The repository supplies default request metadata, not a verified approval inventory; backend reject/remove/forward behavior remains unverified and is not promised here. Documentation-only change; no changeset required. A human should review the full diff before merging. In plain language: asking for a Google permission does not prove that the OAuth app has permission to request it. This guide helps developers check their setup and choose between Composio's app and their own app when sign-in is blocked. <!-- sdk-release-note-exempt: Documentation-only clarification of Google OAuth scope requests and app approval; no published package behavior changes. -->
No changes.