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, 19:45 UTC
docs: clarify HubSpot scope configuration
sjd9021 committed
Jun 18, 2026 at 16:17 UTC
77d883238a2d26c530ce5eb148aee179826425a4
1 file changed
+87
-6
docs/content/toolkits/faq/hubspot.md
+87
-6
@@ -1,11 +1,92 @@
1
-## How do I set up custom OAuth credentials for HubSpot?
1
+## Why do users see a "Connecting an unverified app" warning?
2
3
-For a step-by-step guide on creating and configuring your own HubSpot OAuth credentials with Composio, see [How to create OAuth credentials for HubSpot](https://composio.dev/auth/hubspot).
3
+HubSpot shows this warning when the OAuth app being installed has not been approved by HubSpot's ecosystem review process. The OAuth connection can still work, but HubSpot asks the user to explicitly accept the risk before continuing.
4
5
-## Why am I getting errors with `limit` on HubSpot contact searches?
5
+For Composio-managed HubSpot auth, this depends on Composio's HubSpot app approval status. We are actively working through HubSpot's approval process and expect this to be resolved in the near future. Once the Composio HubSpot app is approved by HubSpot, this warning should stop appearing for new installs that use the approved app.
6
7
-The `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` and `HUBSPOT_LIST_CONTACTS_PAGE` tools have a maximum limit of 100 results per request. Set `limit` to 100 or lower to avoid errors.
7
+For custom auth, the warning depends on your own HubSpot developer app. If your users see this warning with custom credentials, submit your HubSpot app for the relevant HubSpot approval or listing flow.
8
9
-## Why can't I set up webhooks for HubSpot?
9
+## Should I use Composio-managed auth or my own HubSpot OAuth app?
10
11
-HubSpot webhooks require a public app with an App ID and Developer API Key. Private or internal apps cannot receive webhooks.
11
+Use Composio-managed auth when you want the fastest setup and the default Composio HubSpot app covers the permissions you need.
12
+
13
+With Composio-managed HubSpot auth, you can only remove optional scopes that are already available on the Composio-managed HubSpot app.
14
+
15
+You cannot add new scopes to the managed app, and you cannot remove scopes that are non-optional for that managed auth config. If you need a different scope set, create a custom HubSpot OAuth app and configure those scopes there.
16
+
17
+Use your own HubSpot OAuth app when you need a different scope set, your own app name and branding on the consent screen, tighter control over app review and rollout, or a production setup owned by your team. For setup steps, see [How to create OAuth credentials for HubSpot](https://composio.dev/auth/hubspot).
18
+
19
+## How do HubSpot scopes work in Composio?
20
+
21
+The scope category must match between Composio and your HubSpot developer app.
22
+
23
+- Scopes in Composio `scopes` must be configured in HubSpot as **Required** or **Conditionally required**.
24
+- Scopes in Composio `optional_scopes` must be configured in HubSpot as **Optional**.
25
+- Do not request a scope from Composio unless that same scope is enabled in the HubSpot developer app.
26
+
27
+If you use the API, pass the fields in the auth config credentials:
28
+
29
+```json
30
+{
31
+ "credentials": {
32
+ "scopes": "oauth crm.objects.contacts.read",
33
+ "optional_scopes": "crm.objects.companies.read crm.objects.deals.read"
34
+ }
35
+}
36
+```
37
+
38
+Use the [Create Auth Config API](/reference/api-reference/auth-configs/postAuthConfigs) to create the auth config, the [Get Auth Config API](/reference/api-reference/auth-configs/getAuthConfigsByNanoid) to inspect what Composio will request, and the [Update Auth Config API](/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) to change the scope fields.
39
+
40
+When reading an auth config through the API, check both `credentials.scopes` and `credentials.optional_scopes`. Together, they represent the HubSpot permissions Composio can request for that auth config.
41
+
42
+HubSpot's docs may refer to the authorization URL parameter as `optional_scope`; in Composio, the editable auth config field is named `optional_scopes`.
43
+
44
+## What is the recommended custom HubSpot OAuth scope setup?
45
+
46
+For custom auth, we usually recommend keeping the required list minimal:
47
+
48
+```text
49
+oauth
50
+```
51
+
52
+Then put tool-specific HubSpot permissions in `optional_scopes`, and mark those same permissions as optional in your HubSpot developer app.
53
+
54
+The main reason is flexibility. HubSpot requires the scopes in the OAuth URL to match how those scopes are categorized in the HubSpot developer app. If you add a new permission as required in HubSpot, every Composio auth config that uses that app must also request it through `scopes`; otherwise new installs can fail. Keeping tool-specific permissions optional makes it easier to add permissions over time without forcing every auth config to move in lockstep.
55
+
56
+If a permission is mandatory for your product to work, keep it required. Just make sure it is required in HubSpot and sent through Composio `scopes`.
57
+
58
+Example A: all selected permissions are required in HubSpot:
59
+
60
+```json
61
+{
62
+ "credentials": {
63
+ "scopes": "oauth crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read",
64
+ "optional_scopes": ""
65
+ }
66
+}
67
+```
68
+
69
+Example B: only `oauth` is required in HubSpot and the selected tool permissions are optional:
70
+
71
+```json
72
+{
73
+ "credentials": {
74
+ "scopes": "oauth",
75
+ "optional_scopes": "crm.objects.contacts.read crm.objects.contacts.write crm.objects.companies.read crm.objects.companies.write crm.objects.deals.read crm.objects.deals.write tickets timeline"
76
+ }
77
+}
78
+```
79
+
80
+Both are valid. What matters is that Composio and HubSpot agree on which scopes are required and which scopes are optional.
81
+
82
+After changing scopes, reconnect affected HubSpot accounts. Existing connected accounts keep the scopes granted during the original authorization. Optional scopes can let a connection succeed even when a portal cannot grant every permission, but a tool can still fail later if that tool needs a permission the user did not grant.
83
+
84
+## What are common HubSpot troubleshooting checks?
85
+
86
+- **Scope mismatch or callback errors:** confirm every requested scope is enabled in HubSpot and is in the same category in both HubSpot and Composio.
87
+- **Missing-scope tool errors:** add the missing scope to the auth config and HubSpot developer app, then reconnect the account.
88
+- **Contact list/search limit errors:** `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` and `HUBSPOT_LIST_CONTACTS_PAGE` support a maximum `limit` of 100 results per request.
89
+- **Webhook setup errors:** HubSpot webhooks require a public app with an App ID and Developer API Key. Private or internal apps cannot receive webhooks.
90
+- **Refresh or expiry errors:** Common causes include the user revoking the app in HubSpot, HubSpot app credentials changing, the refresh token being invalidated, or the connected account being reauthorized with a different app configuration. After rotating custom OAuth credentials or changing the HubSpot developer app, reconnect affected HubSpot accounts.
91
+
92
+---