HubSpot Service Keys vs Projects-Based Apps: Which Replacement Fits Your Integration?

Choose a HubSpot Service Key for a single-account, system-to-system integration that only needs REST API data access. Choose a Projects-based app when the integration needs webhooks, HubSpot UI components, app lifecycle management, or distribution. For multiple accounts, the app route also requires OAuth. Mixed requirements may justify two separately governed components.

That distinction matters because both routes can produce a Bearer token, but they solve different architecture problems. A token format does not tell you whether the integration can subscribe to events, render an app card, support several customer accounts, or move through a controlled deployment process.

HubSpot describes Service Keys as account-level credentials for data integrations, while its developer platform treats Projects as the source-controlled framework for building app functionality. The decision should therefore start with what the integration does, where it runs, who uses it, and how many accounts it must support.

There is also a product-maturity caveat. As of 16 September 2026, HubSpot’s Service Key documentation labels the feature as public beta and says it remains under active development. Confirm the status, supported scopes, and limits again before making a production commitment.

This choice is easier with a complete inventory. If you have not yet listed which integrations run on legacy private apps, start with the HubSpot API audit checklist.

What is the practical difference between Service Keys and Projects-based apps?

A Service Key grants scoped REST API access to data in one HubSpot account without creating an app project. A Projects-based app packages authentication and application features in a deployable project. It can support webhooks, UI extensions, workflow actions, settings, and distribution patterns that a data-only credential cannot provide.

The cleanest comparison is not “new token versus old token.” It is credential versus application.

HubSpot’s authentication overview adds an important branch inside the app column. A privately distributed app for one standard account can use static authentication. An app intended for multiple accounts must use OAuth, with the distribution configuration determining whether it is limited to approved accounts or prepared for Marketplace listing.

Which questions should drive the architecture decision?

The decision should be made across six dimensions: capability, distribution, event model, user experience, operational ownership, and product maturity. If any required capability is outside the Service Key boundary, the integration needs an app route for that capability. The remaining dimensions then determine its authentication and operating model.

Use these questions in order.

1. Is the integration data-only? Does it simply read or write records through documented REST APIs?

2. Does it react to HubSpot events? If it needs webhook subscriptions, it needs an app.

3. Does it place functionality inside HubSpot? App cards, settings pages, app home pages, and UI extensions belong to a Projects-based app.

4. How many HubSpot accounts will install it? One account can fit static app authentication. Multiple accounts require OAuth.

5. Does it need an application release process? Project configuration, code review, deployable builds, and feature lifecycle controls point toward Projects.

6. Who owns credentials and operations? The owner must be able to grant scopes, rotate secrets, investigate logs, deploy changes, and respond when a dependency changes.

7. Can the business accept beta-product change? A Service Key may be functionally suitable today while its public-beta status still requires an explicit production-readiness decision.

These questions should be answered from observed behavior, code, logs, and current configuration. A legacy app name such as “warehouse connector” is weak evidence. It may hide webhook subscriptions or a UI component added after the original build.

When should you choose a HubSpot Service Key?

Choose a Service Key when one account needs a scoped credential for direct REST API access and the integration has no webhook, UI, app-page, workflow-action, or distribution requirement. This keeps a data integration in an account-managed model and removes the need to build a project solely to obtain API access.

Common fits include:

• a scheduled export from HubSpot to a data warehouse;

• a business-intelligence pipeline that reads CRM records;

• an internal script that updates approved properties;

• a nightly reconciliation job between HubSpot and an internal system;

• a lightweight automation that polls an API endpoint on a defined schedule.

Service Keys can be created and managed by Super Admins and users with Developer tools access. HubSpot’s current documentation shows object-specific scopes, request logs, scope editing, rotation, and deletion in the Development area. The documentation also states that Service Keys are subject to the same limits as privately distributed apps built on the named current platform versions.

The operational advantage is clarity. The account has a dedicated credential for a named data job, and the credential can be scoped and rotated without representing a broader app experience. That still requires standard secret management outside HubSpot: store the key in an approved secrets system, limit runtime access, record its owner, and connect rotation to a tested change procedure.

Do not choose a Service Key merely because the current integration uses a static token. First check what that token supports. HubSpot states that Service Keys cannot authenticate webhooks, calls within a UI extension, or other developer-platform functionality beyond REST API requests. A token swap will not reproduce those capabilities.

When should you choose a Projects-based app?

Choose a Projects-based app when the integration behaves like an application: it subscribes to events, adds functionality inside HubSpot, exposes custom workflow actions, manages app-specific configuration, or must be installed across accounts. Projects provide the configuration and deployment framework needed to operate those features as one managed product.

HubSpot’s current app configuration documentation lists features such as webhook subscriptions, app cards, serverless functions, app events, app objects, settings components, custom workflow actions, and telemetry. The exact feature set depends on the app’s distribution, authentication, platform version, scopes, and product eligibility.

The Projects route then splits by distribution:

OAuth adds its own operating requirements. The integration needs a backend that initiates authorization, stores token data, handles refresh behavior, and maps credentials to the correct account. Installation and reauthorization become part of support. A static single-account app is simpler, but it still carries source configuration, deployment, installation, and feature lifecycle work.

Choose this model because the capabilities or distribution require it, not because Projects is assumed to be the more advanced answer. A nightly data export does not automatically benefit from app cards and deployment infrastructure. In the other direction, an event-driven customer product cannot be reduced to a Service Key without changing its behavior.

When does a hybrid model make sense?

A hybrid model makes sense when one business solution contains two distinct workloads: an application that needs webhooks or HubSpot UI features, and a separate data pipeline that only needs account-level REST API access. Giving each workload its own credential and operating boundary can make scopes, ownership, rotation, monitoring, and incident response easier to reason about.

For example, a revenue-operations system might include:

• a Projects-based app that receives contact-change webhooks and displays account context in an app card; and

• a nightly warehouse export that reads selected CRM objects with a Service Key.

This is an architecture option, not a HubSpot requirement. It creates two components to own, test, and monitor. The separation is worthwhile only when the workloads have meaningfully different capabilities, release cycles, owners, or access profiles.

Use the following test before splitting:

1. Can each component be described as a complete workload with a named owner?

2. Can each use a narrower set of scopes than the combined integration?

3. Can either component be deployed, rotated, paused, and investigated independently?

4. Will the separation reduce coupling rather than duplicate business logic?

5. Is the team prepared to monitor two credentials and reconcile shared data behavior?

If the answer is mostly no, keep the solution within one Projects-based app. If the data job and application already operate as separate systems, the hybrid model may reflect reality more accurately.

How should you choose a replacement for a legacy private app?

Classify the legacy app by its observed functions before selecting a replacement. Data reads and writes alone point toward a Service Key. Webhooks, UI extensions, app pages, or other app features point toward Projects. Multi-account installation adds OAuth. Unclear usage should remain in discovery until logs and code establish the real boundary.

Use this decision path:

The financial and operational stake sits in the wrong boundary. Choosing a Service Key for an app capability can force a second rebuild when the missing webhook, UI, or distribution requirement surfaces. Choosing Projects for a simple extract can add a code and deployment lifecycle that the operating team is not equipped to maintain.

A short technical spike is justified when documentation does not answer a key eligibility or compatibility question. Define the uncertain capability, build the smallest representative test in a developer test account, record the outcome, and feed the evidence into the decision. Do not let a proof of concept become the production migration without the normal scope, security, monitoring, and support review.

What should be verified before migration starts?

Verify product status, endpoint and scope coverage, feature eligibility, distribution limits, permissions, operational ownership, and cutover evidence before migration begins. The architecture choice is provisional until the target route can perform the required work under the real account model and the team can operate its credentials, deployments, logs, and recovery procedure.

Record these items in the architecture decision:

• the current Service Key beta or general-availability status and the date checked;

• every required REST endpoint and scope;

• each webhook, UI extension, workflow action, app page, or custom feature;

• the number and type of HubSpot accounts that need installation;

• static-auth or OAuth requirements;

• the team responsible for code, credentials, deployments, logs, and support;

• token storage, rotation, expiry, revocation, and emergency response procedures;

• current platform version and relevant feature constraints;

• test evidence for data behavior and user workflows;

• a cutover, rollback, monitoring, and decommissioning plan.

HubSpot’s current Service Key page says a planned rotation can keep the original key active for seven days, while an emergency rotation can expire it immediately. Treat that as a product capability to verify at implementation time, then design the application so credentials can change without a code rewrite.

For Projects-based apps, test more than authentication. Confirm the build and upload path, installation, requested scopes, webhook delivery, UI behavior, OAuth account mapping where applicable, and the process for deploying a new project version. The wider HubSpot integration portfolio should also record the owner and support boundary for each component.

The selected model must fit the way the business governs CRM data. HubSpot’s broader data-management capabilities can improve structure and quality inside the platform, but integration credentials still determine which external system can read or change that data.

If your integration mixes data jobs, webhooks, embedded UI, and several account types, Flatline can help map the capability boundary and turn it into an implementation decision. Talk to our team before committing the migration path.

Once the architecture is chosen, the HubSpot API migration plan covers sequencing, testing and rollback, and the overview of HubSpot’s legacy API changes keeps the deadlines in view.

Key takeaways

• A Service Key is an account-level credential for REST API data access. A Projects-based app is a deployable application model.

• Service Keys fit single-account, system-to-system data jobs without webhooks or HubSpot UI components.

• Projects-based apps fit event-driven, embedded, or distributed integrations. Static auth serves a single-account app, while multi-account distribution requires OAuth.

• The right replacement follows observed functionality, distribution, ownership, and operating maturity, not the label on the legacy app.

• A hybrid design can separate a data pipeline from an application when the workloads have distinct scopes, owners, and lifecycles.

• Service Keys remain public beta in HubSpot’s documentation as of 16 September 2026, so status and limits need a fresh check before production use.

The best decision is the smallest model that fully supports the required capability and that the team can operate responsibly. Once that model is chosen, document the evidence, test the target in the real account pattern, and plan migration around complete workflows rather than treating credential replacement as an isolated configuration task.