Tutorial

HubSpot Private Apps erstellen: Der ultimative Guide [2025 Edition]

Melden

Hier ist ein aktuelles, schrittweises Tutorial für das Jahr 2025, um private Apps in HubSpot zu erstellen. Da HubSpot die klassischen API-Keys vollständig durch private Apps ersetzt hat, ist dies der einzige und sicherste Weg, um eigene Integrationen zu bauen.

Private Apps sind die moderne Art, HubSpot mit externen Tools, Ihrer Website oder benutzerdefinierten Skripten zu verbinden. Sie bieten mehr Sicherheit als die alten API-Keys, da Sie genau festlegen können, auf welche Daten (Scopes) die App zugreifen darf.

Schritt 1: Voraussetzungen

Bevor Sie starten, stellen Sie sicher, dass:

  • Sie über Super-Admin-Berechtigungen in Ihrem HubSpot-Portal verfügen.
  • Sie wissen, welche Daten Sie abgreifen oder senden wollen (z. B. Kontakte lesen, Deals schreiben).

Schritt 2: Den Bereich „Private Apps“ aufrufen

  1. Loggen Sie sich in Ihr HubSpot-Konto ein.
  2. Klicken Sie oben rechts in der Hauptnavigationsleiste auf das Zahnrad-Symbol (Einstellungen).
  3. Navigieren Sie in der linken Seitenleiste zu Integrationen > Private Apps.
  4. Klicken Sie oben rechts auf den orangefarbenen Button „Neue private App erstellen“.

Schritt 3: Grundlegende Informationen (Basic Info)

Im ersten Tab geben Sie Ihrer App ein Gesicht:

  • Name: Geben Sie der App einen klaren Namen (z. B. „Website-Formular-Anbindung“ oder „Internes Reporting-Tool“).
  • Logo: Optional können Sie ein Bild hochladen, um die App in der Liste schnell zu erkennen.
  • Beschreibung: Notieren Sie kurz, wofür diese App genutzt wird und wer der Ansprechpartner ist.

Schritt 4: Berechtigungen festlegen (Scopes) – Wichtig!

Klicken Sie auf den Tab Berechtigungen (Scopes). Hier definieren Sie, was die App tun darf.

  • Best Practice 2025: Folgen Sie dem Prinzip der minimalen Rechtevergabe (Least Privilege). Geben Sie der App nur die Rechte, die sie wirklich benötigt.
  • Suchen Sie nach den Kategorien (z. B. crm.objects.contacts).
  • Wählen Sie zwischen Read (Lesen) und Write (Schreiben).
  • Beispiel: Wenn Sie nur Kontakte exportieren wollen, wählen Sie crm.objects.contacts.read.

Schritt 5: App erstellen und Access Token sichern

  1. Klicken Sie oben rechts auf App erstellen.
  2. Es erscheint ein Bestätigungsfenster. Bestätigen Sie die Erstellung.
  3. Nun wird Ihnen Ihr Access Token angezeigt.
  4. WICHTIG: Klicken Sie auf „Anzeigen“ und kopieren Sie den Token. Speichern Sie ihn an einem sicheren Ort (z. B. in einem Passwort-Manager). HubSpot wird Ihnen diesen Token aus Sicherheitsgründen nie wieder im Klartext zeigen, nachdem Sie das Fenster schließen.

Schritt 6: Die App verwenden (Technischer Einsatz)

Im Gegensatz zum alten API-Key wird der Token im Authorization Header Ihrer HTTP-Anfragen verwendet.

So sieht der Header in Ihrem Code aus:

Authorization: Bearer DEIN_ACCESS_TOKEN
Content-Type: application/json

Beispiel-Abfrage (cURL):

curl https://api.hubapi.com/crm/v3/objects/contacts \
  --header "Authorization: Bearer pat-na1-your-awesome-token" \
  --header "Content-Type: application/json"

Schritt 7: Monitoring und Logs (Neu in 2025)

Nachdem Ihre App live ist, können Sie im Bereich „Private Apps“ jederzeit auf den Namen Ihrer App klicken:

  • Logs: Hier sehen Sie die letzten API-Aufrufe. Wenn etwas nicht funktioniert (z. B. ein 403-Fehler), sehen Sie hier, welcher Scope gefehlt hat.
  • Webhooks: Falls Ihre App auf Ereignisse in HubSpot reagieren soll (z. B. „Kontakt wurde gelöscht“), können Sie diese im Tab „Webhooks“ innerhalb der App-Einstellungen konfigurieren.

Profi-Tipps für 2025:

  • Token-Rotation: Wenn Sie vermuten, dass ein Token kompromittiert wurde, können Sie in den App-Einstellungen auf „Token rotieren“ klicken. Der alte Token wird ungültig und ein neuer generiert.
  • Keine API-Keys mehr: Falls Sie noch alte Skripte mit ?hapikey=... nutzen – stellen Sie diese dringend auf Private Apps um, da HubSpot den Support für API-Keys bereits eingestellt hat.
  • Limits: Beachten Sie, dass Private Apps den gleichen API-Limits unterliegen wie Ihr gesamter Account (standardmäßig 250.000 Aufrufe pro Tag für die meisten Pakete).

Viel Erfolg bei Ihrer Integration! Wenn Sie Fragen zu spezifischen Scopes haben, ist die HubSpot Developer Documentation immer die beste Anlaufstelle.

0