# Notes for Custom Service Environment usage

## Developer & CRM Accounts

Embedded users MUST:

1. Have a Developer account in order to create OAuth applications.
2. Have a CRM account in order to test as an end user.
   You will also need to use said Developer account when creating your authentications. **Otherwise your workflows will not work.**

## Custom OAuth Apps

You can create custom OAuth apps to [white-label](https://tray.ai/documentation/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps) your authentication dialogs during integrations.

> **Warning:** **HubSpot is actively migrating all developers to the new Developer Platform (March 2026).** Legacy developer accounts and the UI-based app creation approach are being retired. All new OAuth apps must be created using HubSpot's CLI-based projects framework (version 2025.2+).

The new platform uses a CLI-driven workflow with local configuration files, enabling version control, local development, and repeatable deployments for your OAuth applications.

For migration information, see:

* [Legacy Developer Accounts Migration](https://developers.hubspot.com/changelog/legacy-developer-accounts-migration)
* [Migration Timeline](https://developers.hubspot.com/blog/developer-platform-migration-timeline)
* [Migrate an App](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview)

### Creating Custom OAuth Apps (CLI/Projects Framework)

HubSpot's Developer Platform (version 2025.2+) uses an interactive CLI-based workflow to create and manage OAuth applications.

**Prerequisites:**

* HubSpot CLI version 7.6.0 or later ([installation guide](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli))
* Node.js environment (version 18 or higher)
* Git for version control
* HubSpot developer account (migrated to new platform)

**Creating a new OAuth app:**

1. **Install and authenticate HubSpot CLI**:
   ```bash
   npm install -g @hubspot/cli@latest
   hs account auth
   ```

2. **Create new app project** using interactive CLI:
   ```bash
   hs project create
   ```
   * Select "App" as base contents
   * Choose "Marketplace" or "Private" distribution
   * Select "OAuth" as authentication method
   * Add desired features (webhooks, cards, functions, etc.)
   * CLI generates project structure with all configuration files

3. **Configure redirect URLs** in generated `app-hsmeta.json`:
   * Edit `src/app/app-hsmeta.json` to add your redirect URLs
   * See white-labeling section below for details

4. **Deploy app to HubSpot**:
   ```bash
   hs project upload
   ```

5. **Retrieve credentials** from HubSpot developer portal:
   * Navigate to your app in HubSpot UI
   * Go to Auth tab to find Client ID and Client Secret

6. **Use in Tray** by selecting "Use own OAuth app" and entering credentials

> **Info:** For complete setup instructions, CLI commands, and configuration options, refer to HubSpot's [Create an App guide](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app) and [Developer Platform Overview](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/overview).

**White-labeling:**

To white-label your authentication dialogs, configure redirect URLs in your `app-hsmeta.json` file:

```json
{
  "uid": "my-app",
  "type": "app",
  "config": {
    "name": "My Application Name",
    "auth": {
      "type": "oauth",
      "redirectUrls": [
        "https://auth.tray.io/oauth2/token",
        "https://your-org.integration-authentication.com/oauth2/token"
      ],
      "requiredScopes": ["oauth", "crm.objects.contacts.read"]
    }
  }
}
```

Your first redirect URL should be `https://auth.tray.io/oauth2/token` followed by your custom white-label domain `https://your-org.integration-authentication.com/oauth2/token` (replace `your-org` with your organization name). See [white-labeling documentation](https://tray.ai/documentation/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps) for more details.

> **Info:** If you need a self-hosted redirect URL, contact support as it requires additional setup.

**Scopes:**

Define required scopes in your `app-hsmeta.json` configuration file. However, similar to the legacy approach, it's recommended to leave scopes flexible in your OAuth app and control them when creating authentications in Tray. This allows multiple integrations to use the same custom OAuth app.

**Webhooks:**

If you need webhook functionality with the HubSpot Trigger connector, webhook configuration is also done via files in your project's `src/app/webhooks/` directory. See the [HubSpot Trigger documentation](https://tray.ai/documentation/connectors/service/hubspot/hubspot-trigger) for complete webhook setup instructions including the two-step deployment process.

### Project structure generated by CLI

When you run `hs project create` and select your options, the CLI automatically generates a project structure like this:

```
my-hubspot-app/
├── hsproject.json              # Project definition
├── src/
│   └── app/
│       └── app-hsmeta.json     # App configuration (OAuth settings)
│       └── webhooks/           # If you selected webhooks feature
│           └── webhooks-hsmeta.json
```

**Generated hsproject.json:**

```json
{
  "name": "my-hubspot-app",
  "srcDir": "src",
  "platformVersion": "2025.2"
}
```

**Generated app-hsmeta.json (you'll edit this for redirect URLs):**

```json
{
  "uid": "my-app",
  "type": "app",
  "config": {
    "name": "My Application Name",
    "description": "Custom OAuth app for Tray integrations",
    "auth": {
      "type": "oauth",
      "redirectUrls": [
        "https://auth.tray.io/oauth2/token"
      ],
      "requiredScopes": ["oauth"],
      "optionalScopes": []
    }
  }
}
```

The CLI generates all necessary files based on your selections. You only need to edit configuration values (like redirect URLs and scopes) in the generated files. For complete configuration options, refer to HubSpot's [Create an App guide](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app).

**Retrieving your credentials:**

Once deployed:

1. Navigate to your app in the HubSpot developer portal UI
2. Go to the Auth tab to find your Client ID and Client Secret
3. Copy these credentials for use in Tray (see next section)

## Using Your Custom OAuth App in Tray

After creating your OAuth app in HubSpot (using either the CLI/projects framework or the legacy UI) and obtaining your Client ID and Client Secret, follow these steps to use it in Tray:

### 1 - Add authentication in Tray workflow

In your Tray workflow, click on '**Add authentication**' on the HubSpot connector step, give a name to your auth and click '**Next Step**'
![customOauth HubSpot addAuth](https://tray.ai/documentation/images/connectors/service/hubspot/3KSXE9s00CxmMHe5QqkozU_customOauth_HubSpot_addAuth.png)

### 2 - Select 'Use own OAuth app'

![customOauthApp](https://tray.ai/documentation/images/connectors/service/hubspot/1IUGXldMsF8LCE6EY7i8yr_customOauthApp.png)
Click 'Use own OAuth app' and add the name and description of your auth app.
![customOauth hubspot TraySettings1](https://tray.ai/documentation/images/connectors/service/hubspot/23SnLp0MKQ6RYgDhFepr8B_customOauth_hubspot_TraySettings1.png)

### 3 - Enter Client ID and Client Secret

Paste the Client ID and Client Secret from your HubSpot OAuth app under 'App Key' and 'App Secret' respectively:

* Client ID → App Key
* Client Secret → App Secret

![customOauth hubspot TraySettings2](https://tray.ai/documentation/images/connectors/service/hubspot/269d5UyniYNEc8Ns75ZODy_customOauth_hubspot_TraySettings2.png)

### 4 - Select scopes and create

Select the scopes that you need in your integration:
![customOauth HubSpot addScopes](https://tray.ai/documentation/images/connectors/service/hubspot/6OoeJ5WEkGq9clYu1mjDIU_customOauth_HubSpot_addScopes.png)
Click on 'Create authentication' button and your auth will be attached to the workflow step.

### 5 - End result - White-labeled authentication

Once you publish the solution and it's ready for instance creation, your end users will see a white-labeled auth dialog when creating their authentications.
![customOauthApp HubSpot whitelabelled result](https://tray.ai/documentation/images/connectors/service/hubspot/5EE7O0EXRuOrCkxJG6I7Ue_customOauthApp_Hubspot_Output.png)

## Legacy: UI-based OAuth App Setup

> **Warning:** **This UI-based approach has been deprecated.** HubSpot completed migration of all developer accounts to the new Developer Platform (March 2026). The legacy UI for creating OAuth apps is no longer available. Existing apps created via the UI will continue to work, but all new apps must use the CLI/projects framework documented above.For migration guidance, see:- [Legacy Developer Accounts Migration](https://developers.hubspot.com/changelog/legacy-developer-accounts-migration)
> - [Migrate an App](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview)
> - [Migration Timeline](https://developers.hubspot.com/blog/developer-platform-migration-timeline)

The following steps document the legacy UI-based approach for creating OAuth apps in HubSpot. If you have existing OAuth apps created this way, they will continue to function, but you should plan to migrate them to the new platform.

Once you've created your app using the steps below, see the [Using Your Custom OAuth App in Tray](#using-your-custom-oauth-app-in-tray) section for instructions on configuring it in Tray.

### 1 - Login to HubSpot developers account and click on Create App

You need to get a [HubSpot developer account](https://developers.hubspot.com/). Once you are logged in click on '**Create app**' button on the top right.
![customOauth hubspot CreateApp](https://tray.ai/documentation/images/connectors/service/hubspot/s00SUA9rKhqNdirDWaBjJ_customOauth_hubspot_CreateApp.png)

### 2 - Provide app info

Provide a Public App name and logo for your app. This app would be used by Tray to create authorizations for your Integrations.
![customOauth hubspot AppSettings](https://tray.ai/documentation/images/connectors/service/hubspot/1SkMGDJkS2W6na2lupgBVy_customOauth_hubspot_AppSettings.png)

### 3 - Add Redirect URL

Navigate to the 'Auth' tab next to the 'App info' tab. Copy Client ID and Client secret (as it's hidden, click on show and copy) as they would be used later in Tray.

Now set Redirect URL to `auth.tray.io/oauth2/token`
![customOauth hubspot AuthSettings](https://tray.ai/documentation/images/connectors/service/hubspot/4oxWFsmgqWm20ZKAqhaSdR_customOauth_hubspot_AuthSettings.png)

If you need a [white-labelled solution](https://tray.ai/documentation/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps), you can add another redirect URL `<Your_org_name_here>.integration-authentication.com/oauth2/token`
Example: `your-org.integration-authentication.com/oauth2/token`
![customOauth HubSpot redirectURL](https://tray.ai/documentation/images/connectors/service/hubspot/7lEOUmx2TDir2TIZdEj8Tj_customOauth_Hubspot_redirectURL.png)

> **Info:** Your first redirect URL should still be `auth.tray.io/oauth2/token` followed by `your-org.integration-authentication.com/oauth2/token` in second place. If the service doesn't support more than one redirect URL, check out two workarounds [here](https://tray.ai/documentation/platform/embedded/advanced-features/whitelabelling/custom-oauth-apps#single-redirect-url-issue).

The above URL will replace the redirect URI query parameter in the config wizard/auth-only domain when your end users configure their solution instances.

> **Info:** If you wish to have your self-hosted redirect URL, please contact support as it would require setup from our side.

### Note on scopes

You can add scopes required by your OAuth app however, it's NOT recommended as you would have to create a custom OAuth app for every integration that you create for this service to enforce scope limitation.

A better way would be to leave the scopes as is and control them via the Tray UI when you are adding the auth. In this way, you could have multiple integrations that use the same custom OAuth app and control them right within Tray.

After creating your OAuth app using these steps, continue to the [Using Your Custom OAuth App in Tray](#using-your-custom-oauth-app-in-tray) section above to configure it in your Tray workflows.

## Scopes

Please be aware of the following points when dealing with scopes while using an Embedded account:

* **The scopes you use for your source / master workflow are the scopes that your end users will have when creating the auth**.
* You can also override scopes in the solution editor. This will allow you to specify that **only a subset of the scopes set in the master workflow are available to your End Users**. Please reach out to your Tray technical support if you wish to activate this feature.
  ![hubspot-override-scopes](https://tray.ai/documentation/images/connectors/service/hubspot/4QXuxanekVpVraAcp8AGQd_image.png)
* When creating an OAuth app using HubSpot's CLI, you shouldn't set granular scopes in your configuration file. This way, you would have to create a custom OAuth app for every integration that you create for this service to enforce scope limitation.
  * A better way would be to use the standard method of **setting the scopes when you are creating an authentication in your source / master workflow for each Solution**. This way you can have **multiple integrations that use the same custom OAuth app** and control them within Tray.