HubSpot Service Keys oder Projects-based Apps: Welcher Ersatz passt zu Ihrer Integration?

Wählen Sie einen HubSpot Service Key für eine System-zu-System-Integration in einem einzelnen Account, die nur Datenzugriff über die REST API braucht. Wählen Sie eine Projects-based App, wenn die Integration Webhooks, UI-Komponenten in HubSpot, ein Lifecycle-Management der App oder eine Verteilung auf andere Accounts braucht. Für mehrere Accounts setzt der App-Weg außerdem OAuth voraus. Bei gemischten Anforderungen können zwei getrennt verwaltete Komponenten sinnvoll sein.

Diese Unterscheidung ist wichtig, weil beide Wege ein Bearer-Token erzeugen können, aber unterschiedliche Architekturprobleme lösen. Am Tokenformat lässt sich nicht ablesen, ob die Integration Events abonnieren, eine App Card anzeigen, mehrere Kunden-Accounts bedienen oder einen kontrollierten Deployment-Prozess durchlaufen kann.

HubSpot beschreibt Service Keys als Zugangsdaten auf Account-Ebene für Datenintegrationen, während die Entwicklerplattform Projects als versionskontrolliertes Framework für App-Funktionen behandelt. Die Entscheidung sollte deshalb bei der Frage beginnen, was die Integration tut, wo sie läuft, wer sie nutzt und wie viele Accounts sie unterstützen muss.

Hinzu kommt ein Vorbehalt zur Produktreife. Stand 16. September 2026 führt die Service-Key-Dokumentation von HubSpot die Funktion als Public Beta, die weiterhin aktiv entwickelt wird. Prüfen Sie Status, unterstützte Scopes und Limits erneut, bevor Sie sich für den Produktivbetrieb festlegen.

Diese Wahl fällt leichter mit einer vollständigen Bestandsaufnahme. Wenn Sie noch nicht erfasst haben, welche Integrationen auf Legacy Private Apps laufen, beginnen Sie mit der HubSpot-API-Audit-Checkliste.

Was ist der praktische Unterschied zwischen Service Keys und Projects-based Apps?

Ein Service Key gewährt eingegrenzten REST-API-Zugriff auf Daten in einem HubSpot-Account, ohne dass Sie ein App-Projekt anlegen müssen. Eine Projects-based App bündelt Authentifizierung und App-Funktionen in einem Projekt, das sich deployen lässt. Sie kann Webhooks, UI-Erweiterungen, Workflow-Aktionen, Einstellungen und Verteilungsmodelle unterstützen, die ein reiner Daten-Zugang nicht bieten kann.

Der sauberste Vergleich lautet nicht „neues Token gegen altes Token“. Er lautet Zugangsdaten gegen Anwendung.

Die Übersicht zur Authentifizierung von HubSpot ergänzt in der App-Spalte eine wichtige Verzweigung. Eine privat verteilte App für einen Standard-Account kann statische Authentifizierung nutzen. Eine App für mehrere Accounts muss OAuth verwenden, und die Verteilungskonfiguration legt fest, ob sie auf freigegebene Accounts beschränkt bleibt oder für einen Marketplace-Eintrag vorbereitet wird.

Welche Fragen sollten die Architekturentscheidung leiten?

Die Entscheidung sollte entlang von sechs Dimensionen fallen: Funktionsumfang, Verteilung, Event-Modell, Nutzererlebnis, operative Verantwortung und Produktreife. Liegt eine benötigte Funktion außerhalb dessen, was ein Service Key kann, braucht die Integration für diesen Teil eine App. Die übrigen Dimensionen bestimmen dann Authentifizierung und Betriebsmodell.

Gehen Sie diese Fragen der Reihe nach durch.

1. Geht es bei der Integration nur um Daten? Liest oder schreibt sie lediglich Datensätze über dokumentierte REST APIs?

2. Reagiert sie auf Events in HubSpot? Braucht sie Webhook-Abonnements, braucht sie eine App.

3. Bringt sie Funktionen in HubSpot hinein? App Cards, Einstellungsseiten, App-Startseiten und UI-Erweiterungen gehören zu einer Projects-based App.

4. In wie vielen HubSpot-Accounts wird sie installiert? Zu einem Account passt statische App-Authentifizierung. Mehrere Accounts erfordern OAuth.

5. Braucht sie einen Release-Prozess wie eine Anwendung? Projektkonfiguration, Code-Review, deploybare Builds und Kontrolle über den Lifecycle von Funktionen sprechen für Projects.

6. Wer verantwortet Zugangsdaten und Betrieb? Diese Person oder dieses Team muss Scopes vergeben, Secrets rotieren, Logs untersuchen, Änderungen deployen und reagieren können, wenn sich eine Abhängigkeit ändert.

7. Kann das Unternehmen mit Änderungen an einem Beta-Produkt leben? Ein Service Key kann heute funktional passen, während sein Public-Beta-Status trotzdem eine bewusste Entscheidung zur Produktionsreife verlangt.

Beantworten Sie diese Fragen anhand von beobachtetem Verhalten, Code, Logs und aktueller Konfiguration. Der Name einer Legacy-App wie „Warehouse Connector“ ist ein schwaches Indiz. Dahinter können Webhook-Abonnements oder eine UI-Komponente stecken, die nach dem ursprünglichen Build hinzugekommen sind.

Wann sollten Sie einen HubSpot Service Key wählen?

Wählen Sie einen Service Key, wenn ein Account eingegrenzte Zugangsdaten für direkten REST-API-Zugriff braucht und die Integration keine Anforderungen an Webhooks, Oberfläche, App-Seiten, Workflow-Aktionen oder Verteilung hat. So bleibt eine Datenintegration in einem Modell, das im Account verwaltet wird, und Sie müssen kein Projekt bauen, nur um API-Zugriff zu bekommen.

Typische Einsatzfälle:

• ein geplanter Export aus HubSpot in ein Data Warehouse;

• eine Business-Intelligence-Pipeline, die CRM-Datensätze liest;

• ein internes Skript, das freigegebene Eigenschaften aktualisiert;

• ein nächtlicher Abgleich zwischen HubSpot und einem internen System;

• eine schlanke Automatisierung, die einen API-Endpunkt nach festem Zeitplan abfragt.

Service Keys können von Super Admins und Nutzern mit Zugriff auf Developer tools angelegt und verwaltet werden. Die aktuelle Dokumentation von HubSpot zeigt objektspezifische Scopes, Request-Logs, das Bearbeiten von Scopes, Rotation und Löschung im Bereich Development. Laut Dokumentation gelten für Service Keys außerdem dieselben Limits wie für privat verteilte Apps auf den genannten aktuellen Plattformversionen.

Der operative Vorteil ist Klarheit. Der Account hat eigene Zugangsdaten für einen benannten Datenjob, und diese lassen sich eingrenzen und rotieren, ohne für eine größere App zu stehen. Ein übliches Secret-Management außerhalb von HubSpot bleibt trotzdem nötig: Speichern Sie den Key in einem freigegebenen Secrets-System, beschränken Sie den Zugriff zur Laufzeit, dokumentieren Sie die verantwortliche Person und koppeln Sie die Rotation an ein getestetes Änderungsverfahren.

Wählen Sie einen Service Key nicht nur deshalb, weil die aktuelle Integration ein statisches Token nutzt. Prüfen Sie zuerst, was dieses Token unterstützt. Laut HubSpot können Service Keys weder Webhooks noch Aufrufe innerhalb einer UI-Erweiterung noch andere Funktionen der Entwicklerplattform jenseits von REST-API-Anfragen authentifizieren. Ein Token-Tausch bildet diese Funktionen nicht nach.

Wann sollten Sie eine Projects-based App wählen?

Wählen Sie eine Projects-based App, wenn sich die Integration wie eine Anwendung verhält: Sie abonniert Events, bringt Funktionen in HubSpot hinein, stellt eigene Workflow-Aktionen bereit, verwaltet App-spezifische Einstellungen oder muss in mehreren Accounts installiert werden. Projects liefern das Konfigurations- und Deployment-Framework, um diese Funktionen als ein verwaltetes Produkt zu betreiben.

Die aktuelle Dokumentation zur App-Konfiguration von HubSpot nennt Funktionen wie Webhook-Abonnements, App Cards, Serverless Functions, App Events, App Objects, Einstellungskomponenten, eigene Workflow-Aktionen und Telemetrie. Welche Funktionen genau verfügbar sind, hängt von Verteilung, Authentifizierung, Plattformversion, Scopes und Produktberechtigung der App ab.

Der Projects-Weg teilt sich dann nach Verteilung auf:

OAuth bringt eigene betriebliche Anforderungen mit. Die Integration braucht ein Backend, das die Autorisierung startet, Token-Daten speichert, das Erneuern von Tokens abwickelt und Zugangsdaten dem richtigen Account zuordnet. Installation und erneute Autorisierung werden Teil des Supports. Eine statische App für einen Account ist einfacher, bringt aber ebenfalls Arbeit an Quellkonfiguration, Deployment, Installation und Lifecycle der Funktionen mit sich.

Wählen Sie dieses Modell, weil der Funktionsumfang oder die Verteilung es verlangen, nicht weil Projects automatisch als die fortschrittlichere Antwort gilt. Ein nächtlicher Datenexport profitiert nicht automatisch von App Cards und Deployment-Infrastruktur. Umgekehrt lässt sich ein ereignisgesteuertes Kundenprodukt nicht auf einen Service Key reduzieren, ohne sein Verhalten zu ändern.

Wann ist ein hybrides Modell sinnvoll?

Ein hybrides Modell ist sinnvoll, wenn eine Geschäftslösung aus zwei getrennten Workloads besteht: einer Anwendung, die Webhooks oder UI-Funktionen in HubSpot braucht, und einer separaten Datenpipeline, die nur REST-API-Zugriff auf Account-Ebene benötigt. Erhält jeder Workload eigene Zugangsdaten und eigene Betriebsgrenzen, lassen sich Scopes, Verantwortung, Rotation, Monitoring und Incident-Response oft leichter überblicken.

Ein Revenue-Operations-System könnte zum Beispiel bestehen aus:

• einer Projects-based App, die Webhooks zu Kontaktänderungen empfängt und Account-Kontext in einer App Card anzeigt; und

• einem nächtlichen Warehouse-Export, der ausgewählte CRM-Objekte mit einem Service Key liest.

Das ist eine Architekturoption, keine Vorgabe von HubSpot. Sie erzeugt zwei Komponenten, die verantwortet, getestet und überwacht werden müssen. Die Trennung lohnt sich nur, wenn sich die Workloads in Funktionsumfang, Release-Zyklen, Zuständigkeiten oder Zugriffsprofilen deutlich unterscheiden.

Machen Sie vor dem Aufteilen diesen Test:

1. Lässt sich jede Komponente als vollständiger Workload mit benannter verantwortlicher Person beschreiben?

2. Kommt jede Komponente mit weniger Scopes aus als die kombinierte Integration?

3. Lässt sich jede Komponente unabhängig deployen, rotieren, pausieren und untersuchen?

4. Verringert die Trennung die Kopplung, statt Geschäftslogik zu duplizieren?

5. Ist das Team bereit, zwei Zugangsdaten zu überwachen und gemeinsames Datenverhalten abzustimmen?

Lautet die Antwort überwiegend nein, halten Sie die Lösung in einer Projects-based App. Laufen Datenjob und Anwendung bereits als getrennte Systeme, bildet das hybride Modell die Realität möglicherweise genauer ab.

Wie wählen Sie einen Ersatz für eine Legacy Private App?

Ordnen Sie die Legacy-App nach ihren beobachteten Funktionen ein, bevor Sie einen Ersatz wählen. Reines Lesen und Schreiben von Daten spricht für einen Service Key. Webhooks, UI-Erweiterungen, App-Seiten oder andere App-Funktionen sprechen für Projects. Installation in mehreren Accounts bringt OAuth ins Spiel. Ist die Nutzung unklar, bleiben Sie in der Analysephase, bis Logs und Code die tatsächliche Grenze zeigen.

Nutzen Sie diesen Entscheidungspfad:

Das finanzielle und operative Risiko liegt in einer falsch gezogenen Grenze. Wer einen Service Key für eine App-Funktion wählt, riskiert einen zweiten Neubau, sobald die fehlende Anforderung an Webhooks, Oberfläche oder Verteilung auftaucht. Wer Projects für einen einfachen Export wählt, fügt womöglich einen Code- und Deployment-Lifecycle hinzu, den das Betriebsteam nicht pflegen kann.

Ein kurzer technischer Spike ist gerechtfertigt, wenn die Dokumentation eine wichtige Frage zu Berechtigung oder Kompatibilität nicht beantwortet. Benennen Sie die unsichere Funktion, bauen Sie den kleinsten aussagekräftigen Test in einem Entwickler-Testaccount, dokumentieren Sie das Ergebnis und lassen Sie diesen Beleg in die Entscheidung einfließen. Lassen Sie einen Proof of Concept nicht ohne die übliche Prüfung von Scopes, Sicherheit, Monitoring und Support zur Produktivmigration werden.

Was sollte vor Beginn der Migration geprüft werden?

Prüfen Sie Produktstatus, Abdeckung von Endpunkten und Scopes, Berechtigung für Funktionen, Verteilungslimits, Rechte, operative Verantwortung und Belege für die Umstellung, bevor die Migration beginnt. Die Architekturentscheidung ist vorläufig, bis der gewählte Weg die nötige Arbeit im realen Account-Modell leisten kann und das Team Zugangsdaten, Deployments, Logs und Wiederherstellung im Griff hat.

Halten Sie diese Punkte in der Architekturentscheidung fest:

• den aktuellen Status der Service Keys, Beta oder allgemein verfügbar, und das Datum der Prüfung;

• jeden benötigten REST-Endpunkt und jeden benötigten Scope;

• jeden Webhook, jede UI-Erweiterung, Workflow-Aktion, App-Seite oder eigene Funktion;

• Anzahl und Art der HubSpot-Accounts, in denen installiert werden muss;

• Anforderungen an statische Authentifizierung oder OAuth;

• das Team, das für Code, Zugangsdaten, Deployments, Logs und Support verantwortlich ist;

• Verfahren für Token-Speicherung, Rotation, Ablauf, Widerruf und Notfälle;

• die aktuelle Plattformversion und relevante Einschränkungen von Funktionen;

• Testbelege für Datenverhalten und Nutzer-Workflows;

• einen Plan für Umstellung, Rollback, Monitoring und Stilllegung.

Laut der aktuellen Service-Key-Seite von HubSpot kann eine geplante Rotation den ursprünglichen Key noch sieben Tage aktiv halten, während eine Notfallrotation ihn sofort ablaufen lässt. Behandeln Sie das als Produktfunktion, die Sie bei der Implementierung erneut prüfen, und gestalten Sie die Anwendung so, dass sich Zugangsdaten ändern lassen, ohne Code neu zu schreiben.

Testen Sie bei Projects-based Apps mehr als die Authentifizierung. Prüfen Sie Build- und Upload-Pfad, Installation, angeforderte Scopes, Zustellung der Webhooks, Verhalten der Oberfläche, gegebenenfalls die Zuordnung von OAuth zu Accounts und den Prozess für das Deployment einer neuen Projektversion. Im übergreifenden Portfolio Ihrer HubSpot-Integrationen sollten außerdem für jede Komponente die verantwortliche Person und die Grenze des Supports festgehalten sein.

Das gewählte Modell muss dazu passen, wie das Unternehmen seine CRM-Daten steuert. Die breiteren Datenmanagement-Funktionen von HubSpot können Struktur und Qualität innerhalb der Plattform verbessern, doch die Zugangsdaten der Integrationen bestimmen weiterhin, welches externe System diese Daten lesen oder ändern darf.

Verbindet Ihre Integration Datenjobs, Webhooks, eingebettete Oberflächen und mehrere Account-Typen? Dann hilft Ihnen Flatline, die Grenzen des Funktionsumfangs zu bestimmen und daraus eine Implementierungsentscheidung zu machen. Sprechen Sie mit unserem Team, bevor Sie sich auf einen Migrationspfad festlegen.

Steht die Architektur fest, behandelt der HubSpot-API-Migrationsplan Reihenfolge, Tests und Rollback, und der Überblick über die Legacy-API-Änderungen von HubSpot behält die Fristen im Blick.

Das Wichtigste in Kürze

• Ein Service Key ist ein Zugang auf Account-Ebene für Datenzugriff über die REST API. Eine Projects-based App ist ein deploybares Anwendungsmodell.

• Service Keys passen zu System-zu-System-Datenjobs in einem einzelnen Account, ohne Webhooks oder UI-Komponenten in HubSpot.

• Projects-based Apps passen zu ereignisgesteuerten, eingebetteten oder verteilten Integrationen. Statische Authentifizierung reicht für eine App in einem Account, die Verteilung auf mehrere Accounts erfordert OAuth.

• Der richtige Ersatz ergibt sich aus beobachteter Funktion, Verteilung, Verantwortung und betrieblicher Reife, nicht aus dem Namen der Legacy-App.

• Ein hybrides Design kann eine Datenpipeline von einer Anwendung trennen, wenn die Workloads unterschiedliche Scopes, Zuständigkeiten und Lifecycles haben.

• Service Keys sind laut HubSpot-Dokumentation mit Stand 16. September 2026 weiterhin Public Beta. Status und Limits sollten Sie daher vor dem Produktiveinsatz neu prüfen.

Die beste Entscheidung ist das kleinste Modell, das den benötigten Funktionsumfang vollständig abdeckt und das Ihr Team verantwortungsvoll betreiben kann. Steht das Modell fest, dokumentieren Sie die Belege, testen Sie das Ziel im realen Account-Muster und planen Sie die Migration entlang vollständiger Workflows, statt den Austausch von Zugangsdaten als isolierte Konfigurationsaufgabe zu behandeln.