Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 |  |
| 29 | 3. Enter the app name, description, logo, and support information. Users see these details when they authorize the app. |
| 30 | |
| 31 |  |
| 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 |  |
| 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 |  |
| 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. |