Legacy Apps and v1–v3 APIs - Migrate by September 2027

Develop, Build & Integrate
, , ,
1

At Fall Spotlight on September 15, HubSpot is announcing the end of support for v1-v3 APIs, legacy public apps, and legacy private apps, all with a September 2027 enforcement date. If your integration or app uses any of these, you have a 12-month window to migrate.

This changelog covers v1-v3. Support for v4 is ending on its own separate timeline, March 30, 2027, which was announced earlier this year. See the previously published v4 changelog for that timeline.

This post covers breaking changes only. For everything new and non-breaking in this release, including the APIs reaching general availability, the updated APIs, the new public betas, and the latest AI builder tools, see the Fall Spotlight 2026 developer rollup.

What’s Changing

Three simultaneous announcements share the same enforcement date: September 2027.

1. API versions v1-v3 are going unsupported

Endpoints using numbered version paths, /v1/, /v2/, and /v3/, will move to unsupported status. HubSpot will no longer release bug fixes, reliability improvements, or security updates for these versions. After September 2027, these endpoints will be unsupported. (Support for v4 is ending separately on March 30, 2027, announced earlier this year. See the v4 support timeline.)

Migrate directly from any legacy version to date-based versioning (DBV). Do not use v3 or v4 as an intermediate step. See the DBV migration guide for the full process, including endpoints where the response shape changes, not just the URL path.

2. Legacy public apps are going unsupported

Public apps created before June 23, 2026 use HubSpot’s pre-Projects app architecture. These apps move to unsupported status on September 15, with enforcement in September 2027. To remain listed in the Marketplace and retain certification, migrate to the current Projects-based app model. See the app migration guide.

3. Legacy private apps must migrate

Private apps built before the Projects-based private app model was introduced must also migrate to Projects-based private apps by September 2027. This is a separate announcement from the public app change.

If you’re building a new private integration, use Service Keys (now available) instead of creating a new legacy private app. Service Keys are the recommended path for lightweight integrations, internal tools, and AI agent integrations, with no full OAuth backend required. See the Service Keys documentation.

Note: legacy private app creation is disabled on September 28, 2026 for new accounts and October 26, 2026 for existing accounts.

For marketplace apps: two compliance requirements

Apps in the HubSpot Marketplace must meet both requirements to remain listed and retain certification. They apply independently, so you need to address both.

  1. Using unsupported API versions (v1-v4) after September 2027: your app loses its certification status.
  2. Running on legacy app architecture (pre-Projects) after September 2027: your app is eligible for delisting.

An app that has migrated to Projects but still calls v1-v4 APIs is still at risk of losing certification. An app using date-based APIs but still on legacy app architecture is still at risk of delisting.

How to prepare

  1. Check which APIs your apps use. Starting September 15, the developer home tasks card shows “X of your apps use APIs becoming unsupported” and links to the migrations tab. Note: detection checks API calls at runtime, not your source code. Runtime calls to legacy endpoints will be flagged even if your codebase has been updated.
  2. Check your app architecture. Go to your Developer Home or Projects list to confirm whether your apps are Projects-based or legacy.
  3. Check your private apps. If you have any private apps created before the Projects-based private app model, those also need to migrate.
  4. Migrate using the guides. The DBV migration guide covers API versioning. The app migration guide covers app architecture.
  5. Watch the developer changelog for endpoint documentation. Not all legacy replacement paths are finalized yet. The March 2027 DBV release will include full per-endpoint replacement documentation for every legacy API. You have until September 2027, so plan your timeline accordingly.

When is it happening?

Date Milestone
September 15, 2026 All three changes announced; 12-month migration window opens
September 28, 2026 Legacy private app creation ends for new accounts
October 26, 2026 Legacy private app creation ends for existing accounts
September 2027 Enforcement; legacy APIs unsupported, legacy public apps and private apps unsupported

Starting September 15, the developer home tasks card is the fastest way to see your specific impact. Migration guides are available for API versioning and app architecture.

Questions? Ask down below!

2

As of today, 21-September, Service Keys are still BETA and hence not production-ready. With Service Keys being the recommended replacement for Private Apps, the timeline above does not make sense.

Here are the specific concerns I have for my team:

  1. When are Service Keys GA? A BETA feature that can have breaking changes without advance notice to customers or a GA-support lifecycle is not a suitable replacement for an existing GA feature.
  2. An announcement was not made until 15-Sep which does not allow a reasonable timeline to prioritize this maintenance work for development teams. When we looked at Service Keys a couple of months ago and did some light testing, there was breakage to resolve, hence not a dead simple replacement task.
  3. Whereas this announcement may have been intended for existing accounts to prevent net new app creation as of 26-Oct, it has the consequence of preventing us from creating existing Private Apps again in Sandboxes that we manage or refresh as well.
3

Hello, thank you for your response! I wanted to clarify some things for you moving forward.

  1. Service Keys should be going into GA by the end of this month. Please make sure you’re subscribed to the changelog and newsletter to get the most up-to-date releases.

  2. You have 12 months until September 2027 before things become unsupported. That should give your team enough runway to make the migration easier for you. We’re also releasing new migration tools in the Development section of your HubSpot account to help with migrations, by giving you a list of your apps and what needs to be updated and by when.

  3. I understand the frustration of Legacy private apps being unable to be updated starting in October 26. In this case, please determine how you’re using those private apps and migrate them to Service Keys, which again, are going into GA at the end of this month, September.

Thank you and I hope this clears things up!

4

Thanks for the response. Service Keys becoming GA clears up concern #1, but #2 and #3 are still an issue. If existing Private Apps are not able to be re-created in new Sandbox environments post-Oct 26, then we are not able to run our existing integrations using the legacy setup until our migration to Service Keys is complete (which may not occur until after Oct 26 due to competing priority work, and given that we know there will be some breaking changes from prior testing).

In short - the timing of removing access to create existing Private Apps is still problematic, because that change disrupts the intended 12-month timeline to complete our transition to service keys.

This issue can be fully resolved by extending the timeline for existing customers to create Private Apps. Q4 is a busy time for my team, thus a Q1 cutoff would be more reasonable so that we can work this maintenance project in amongst our other priorities.

5

Thanks for the response. Legacy private apps will be supported until next September 2027, so you have time to migrate things to Service Keys on your timeline. I hope this length of window can give you time to transition.

6

Thanks, but this still doesn’t address my timeline concern.

I understand existing legacy private apps (runtime) are supported until September 2027. The issue is the October 26, 2026 cutoff for creating legacy private apps, which affects sandbox refreshes and recreating existing setups before our Service Keys migration is complete.

Can HubSpot either extend legacy private app creation for existing customers into 2027, or provide the supported workaround for provisioning legacy private apps in refreshed/new sandbox environments from October 26, 2026 through 2027 until our service key migration is complete?

11

Is there a timeline or roadmap on when the hubspot/api-clientin Workflows will be updated to support the new versioned endpoints?

12

The sandbox point is the part I’d test early. I’d include credential recreation in the migration test, not just whether the new endpoints work. A setup can run fine today but still be imposible to recreate after a sandbox refresh if part of the provisioning path depends on creating a legacy private app.

For anything we expect to survive into 2027, I’d want to know we can rebuild the auth +integration from scratch using only the supported path. That catch a different failure than normal API compatibility testing