@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
md 128 lines 8.69 KB
Rendered Raw
1 ## Why do users see a "Connecting an unverified app" warning?
2
3 HubSpot shows this warning because the default Composio-managed HubSpot OAuth app is still awaiting HubSpot approval. The connection can still work, but HubSpot asks the user to explicitly accept the warning before continuing.
4
5 Composio is working on getting the default HubSpot OAuth app approved, but there is no concrete ETA because the final review timeline depends on HubSpot.
6
7 If this warning blocks your rollout, use your own HubSpot OAuth app credentials in a custom Composio auth config. That lets you control the app identity, review status, and consent screen shown to your users.
8
9 ## Should I use Composio-managed auth or my own HubSpot OAuth app?
10
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. Setup steps are in the next question.
18
19 ## How do I set up custom OAuth credentials for HubSpot?
20
21 Use your own HubSpot app when you need your own scope set, app name, or consent screen, or when the unverified-app warning blocks your rollout.
22
23 ### Create the HubSpot app
24
25 1. Create a developer account in the [HubSpot developer portal](https://developers.hubspot.com/get-started). HubSpot public apps must belong to a developer account.
26 2. In the developer account, open **Apps** and click **Create App**.
27
28 ![HubSpot Apps page with the Create app button](/images/toolkits/hubspot/create-app.webp)
29 3. Enter the app name, description, logo, and support information. Users see these details when they authorize the app.
30
31 ![HubSpot app App Info tab with name, logo and description fields](/images/toolkits/hubspot/app-info.webp)
32 4. Open the **Auth** tab and copy the **Client ID** and **Client Secret**.
33 5. In **Redirect URLs**, below the credentials, add `https://backend.composio.dev/api/v1/auth-apps/add`. It must exactly match the `oauth_redirect_uri` field in your Composio auth config.
34 6. Enable the scopes your integration needs, marking each as required or optional to match how you'll list it in Composio (see the scope questions below).
35
36 ### Create the auth config in Composio
37
38 1. In the Composio dashboard, go to **Auth Configs**, click **Create Auth Config**, and select **HubSpot**.
39 2. Set the authentication type to **OAuth2** (not Bearer Token) and choose **Use your own developer authentication**.
40
41 ![Use your own developer credentials toggle turned on in the Composio auth config](/images/toolkits/hubspot/use-own-credentials.webp)
42 3. Paste the **Client ID** and **Client Secret**. Set `scopes` and `optional_scopes` to match the required and optional scopes in your HubSpot app, then click **Create HubSpot Auth Config**.
43
44 ![Composio auth config Client id and Client secret fields](/images/toolkits/hubspot/composio-client-fields.webp)
45 4. Click **Connect Account**, authorize the app in HubSpot, and confirm the account shows as **Active**.
46
47 See [Custom auth configs](/docs/auth-configuration/custom-auth-configs) for the general flow. The default auth config requests a broad CRM scope set in `scopes` and `transactional-email automation marketing.campaigns.read marketing.campaigns.write` in `optional_scopes`. Every requested scope must be enabled in your HubSpot app, or HubSpot rejects the authorization. See HubSpot's [scopes reference](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/scopes) for the full list.
48
49 ## How do scopes work in HubSpot?
50
51 The scope category must match between Composio and your HubSpot developer app.
52
53 - Scopes in Composio `scopes` must be configured in HubSpot as **Required** or **Conditionally required**.
54 - Scopes in Composio `optional_scopes` must be configured in HubSpot as **Optional**.
55 - Do not request a scope from Composio unless that same scope is enabled in the HubSpot developer app.
56
57 If you use the API, pass the fields in the auth config credentials:
58
59 ```json
60 {
61 "credentials": {
62 "scopes": "oauth crm.objects.contacts.read",
63 "optional_scopes": "crm.objects.companies.read crm.objects.deals.read"
64 }
65 }
66 ```
67
68 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.
69
70 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.
71
72 HubSpot's docs may refer to the authorization URL parameter as `optional_scope`; in Composio, the editable auth config field is named `optional_scopes`.
73
74 ## What is the recommended custom HubSpot OAuth scope setup?
75
76 For custom auth, we usually recommend keeping the required list minimal:
77
78 ```text
79 oauth
80 ```
81
82 Then put tool-specific HubSpot permissions in `optional_scopes`, and mark those same permissions as optional in your HubSpot developer app.
83
84 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.
85
86 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`.
87
88 Example A: all selected permissions are required in HubSpot:
89
90 ```json
91 {
92 "credentials": {
93 "scopes": "oauth crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read",
94 "optional_scopes": ""
95 }
96 }
97 ```
98
99 Example B: only `oauth` is required in HubSpot and the selected tool permissions are optional:
100
101 ```json
102 {
103 "credentials": {
104 "scopes": "oauth",
105 "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"
106 }
107 }
108 ```
109
110 Both are valid. What matters is that Composio and HubSpot agree on which scopes are required and which scopes are optional.
111
112 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.
113
114 ## What are common HubSpot troubleshooting checks?
115
116 - **Scope mismatch or callback errors:** confirm every requested scope is enabled in HubSpot and is in the same category in both HubSpot and Composio.
117 - **Missing-scope tool errors:** add the missing scope to the auth config and HubSpot developer app, then reconnect the account.
118 - **Contact list/search limit errors:** `HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA` and `HUBSPOT_LIST_CONTACTS_PAGE` support a maximum `limit` of 100 results per request.
119 - **Webhook setup errors:** HubSpot webhooks require a public app with an App ID and Developer API Key. Private or internal apps cannot receive webhooks.
120 - **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.
121
122 ## HubSpot auth loops can be caused by HubSpot-side workspace/login state
123
124 If the HubSpot flow loops while Composio works on its side, retry while logged into the correct HubSpot workspace and confirm the OAuth app is public/configured correctly.
125
126 ## HubSpot triggers require each user’s own app ID and developer API key
127
128 HubSpot webhook APIs need the specific HubSpot app that should receive webhook notifications. For user HubSpot triggers, `app_id` and developer API key are required because each user needs their own HubSpot app for webhook delivery.