> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to OAuth

> Switch HubSpot from a Private App access token to the OpenCX OAuth Public App without recreating tickets or signatures.

OpenCX now uses the HubSpot OAuth Public App for new HubSpot connections. If your organization still uses a Private App access token, migrate from the HubSpot integration modal.

## Why migrate

* **Private Apps are the legacy path.** New features such as workflow extensions only work on OAuth.
* **One click instead of token paste.** No more creating a HubSpot Private App, copying scopes, pasting access tokens, or configuring webhooks manually.
* **Better security.** OAuth tokens are short-lived and refreshed automatically. Private App tokens remain valid until rotated or revoked.
* **Faster agent takeover.** HubSpot ownership changes can pause the AI without waiting for the next customer message.

## What changes

|                                | Legacy Private App                          | OAuth Public App                                                                     |
| ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------ |
| Setup                          | Create app, paste token, configure webhooks | Approve OpenCX on HubSpot's consent screen                                           |
| Access token                   | Paste-and-store                             | Issued and refreshed automatically                                                   |
| Webhook URL                    | Manually copied into HubSpot                | Subscribed automatically on install                                                  |
| Workflow extensions in HubSpot | Not available                               | "Pause OpenCX AI", "Resume OpenCX AI", "Send to OpenCX AI", "Request OpenCX handoff" |
| Agent ownership changes        | Slower fallback behavior                    | Processed by the OAuth app event path                                                |

## How to migrate

1. In OpenCX, open **Settings → Integrations → HubSpot**.
2. Choose **OAuth Public App**. If your org is still on Private App auth, the modal shows an **Action recommended** banner.
3. Click **Connect with HubSpot**. HubSpot opens its consent screen.
4. Approve the requested permissions.
5. You'll bounce back to OpenCX with a "HubSpot connected" toast. The integration card now shows **Connected**.
6. **Optional:** in HubSpot, delete the OpenCX Private App you previously created. The new OAuth app supersedes it.

Your existing tickets, conversations, sessions, and email signature settings stay intact during the switch.

## Frequently asked questions

### Do I lose any tickets or conversation history during the switch?

No. The migration only touches the auth tokens. Your `chat_sessions`, `chat_history`, ticket links, and signature settings are untouched.

### What if I have multiple HubSpot portals?

OpenCX currently supports one HubSpot portal per OpenCX organization. Reconnecting via OAuth will use the portal of whoever clicks Connect.

### Can I roll back if something breaks?

Usually, yes. If your workspace still shows **Private App (legacy)**, you can reconnect with the previous token path. Some organizations are OAuth-only, so the legacy form may be hidden.

### What happens to the workflow actions if I'm on legacy?

Workflow actions only work on the OAuth path. Until you migrate, **Pause / Resume / Send-to-AI / Request handoff** won't appear inside HubSpot's Workflow builder for your portal.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup and legacy fallback.
  </Card>

  <Card title="Handoff & Sync" icon="arrow-right-arrow-left" href="/integrations/hubspot/handoff">
    Day-to-day ticket and conversation behavior.
  </Card>

  <Card title="Webhook Reference" icon="webhook" href="/integrations/hubspot/webhooks">
    Events OpenCX receives and writes back.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Reconnect prompts and sync issues.
  </Card>
</CardGroup>