Private apps

Mithilfe von privaten Apps können Sie die APIs von HubSpot nutzen, um auf bestimmte Daten Ihres HubSpot-Accounts zuzugreifen. Sie können autorisieren, was jede private App in Ihrem Account anfordern oder ändern darf. Dadurch wird ein Zugriffstoken generiert, das für Ihre App einzigartig ist. 

Für den Zugriff auf private Apps in Ihrem HubSpot-Account müssen Sie ein Super-Admin sein.

Bitte beachten: Private Apps unterstützen benutzerdefinierte Chronikeinträge nicht. Webhooks werden in privaten Apps unterstützt, aber Abonnements können nicht programmgesteuert über eine API bearbeitet werden und müssen stattdessen in den Einstellungen Ihrer privaten App bearbeitet werden.

Wenn Sie vorhaben, eine App mit benutzerdefinierten Chronikeinträgen zu erstellen, sollten Sie stattdessen eine öffentliche App erstellen. Erfahren Sie mehr über die Unterschiede zwischen privaten und öffentlichen Apps.

Eine private App erstellen

  • Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf das Zahnradsymbol.
  • Gehen Sie in der linken Seitenleiste zu Integrationen > Private Apps.
  • Klicken Sie auf Private App erstellen.
  • Konfigurieren Sie auf der Registerkarte Grundlegende Informationen die Details Ihrer App:
    • Geben Sie den Namen Ihrer App ein.
    • Bewegen Sie den Mauszeiger über das Platzhalterlogo und klicken Sie auf das Symbol zum Hochladen, um ein quadratisches Bild hochzuladen, das als Logo für Ihre App dienen soll.
    • Geben Sie eine Beschreibung für Ihre App ein.
  • Klicken Sie auf die Registerkarte Bereiche.
  • Aktivieren Sie das Kontrollkästchen Lesen oder Schreiben für jeden Bereich, auf den Ihre private App zugreifen können soll. Sie können auch über die Suchleiste Bereich suchen nach einem bestimmten Bereich suchen.
  • Ist Ihre App fertig konfiguriert, klicken Sie oben rechts auf App erstellen.

updated-read-write-scope-config-private-apps

  • Überprüfen Sie im Dialogfeld die Informationen zum Zugriffstoken Ihrer App und klicken Sie dann auf Mit dem Erstellen fortfahren.

Sobald Ihre App erstellt ist, können Sie mithilfe des Zugriffstokens der App API-Aufrufe durchführen. Wenn Sie die Informationen zu Ihrer App bearbeiten oder ihre Bereiche ändern müssen, klicken Sie auf Details bearbeiten.

edit-details-of-private-app

 

API-Aufrufe mit dem Zugriffstoken Ihrer App durchführen

Bitte beachten: Private Apps verlieren den Zugriff auf Bereiche, wenn Ihr HubSpot-Account herabgestuft wird, und verlieren den Zugriff auf Funktionen. Wenn Ihr Account beispielsweise keinen Zugriff auf HubDB hat, hat Ihre private App keinen Zugriff auf den HubDB-Bereich.

Zugriffstoken privater Apps werden aktualisiert, um die verfügbaren Bereiche in Ihrem HubSpot-Account und Ihre Konfiguration der privaten App widerzuspiegeln. Die Token-Zeichenfolge selbst ändert sich jedoch nicht. 

Um API-Aufrufe durchzuführen, gehen Sie zur Detailseite Ihrer App.

  • Klicken Sie auf der Zugriffstoken-Karte auf Token anzeigen, um Ihr Zugriffstoken offenzulegen. Klicken Sie auf Kopieren, um das Token in Ihre Zwischenablage zu kopieren.

show-private-app-access-token-1

  • Sie können dann das Zugriffstoken einfügen, um es Ihren Entwicklern zur Verfügung zu stellen, oder es selbst bei der Entwicklung Ihrer App verwenden. Legen Sie beim Aufrufen eines HubSpot-API-Endpunkts den Wert des Feldes Autorisierung auf Bearer [YOUR_TOKEN]. Wenn Sie zum Beispiel die Kontakte-API mit Node.js und axios aufrufen, würde die Anfrage wie folgt aussehen:
axios.get('https://api.hubapi.com/crm/v3/objects/contacts', { headers: { 'Authorization': `Bearer ${YOUR_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );
  • Zugriffstoken von privaten Apps werden auf Basis von OAuth implementiert, sodass Sie auch authentifizierte Aufrufe mit Ihrem Zugriffstoken unter Verwendung einer der HubSpot-Client-Bibliotheken durchführen können. Wenn Sie zum Beispiel die Node.js-Client-Bibliothek verwenden, können Sie einen OAuth-Client instanziieren, indem Sie das Zugriffstoken Ihrer App übergeben:
const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN });

Informationen zu Zugriffstoken für private Apps anzeigen

Um Informationen zum Zugriffstoken einer privaten App anzuzeigen, z. B. die Hub-ID und mit dem Token verbundene Bereiche, führen Sie eine POST-Anfrage an /oauth/v2/private-apps/get/access-token-info durch. Geben Sie im Text der Anfrage Ihr Zugriffstoken an:

// POST request response body { "tokenKey": {{accessToken}} }

Die Antwort enthält Informationen zum Benutzer, der das Token erstellt hat, die Hub-ID des Accounts, die ID der privaten App und die mit dem Token verbundenen Bereiche.

// Example response body { userId:123456, hubId:1020304, appId:2011410, scopes:[ "oauth", "crm.schemas.companies.write"] }

Das Zugriffstoken rotieren

Wenn Ihr Zugriffstoken verloren gegangen ist oder anderweitig kompromittiert wurde, können Sie das Token rotieren. Es wird ein neues Zugriffstoken erstellt und das ursprüngliche Zugriffstoken verfällt.

  • Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf die Seite mit den Einstellungen.
  • Gehen Sie zu Integrationen > Private Apps.
  • Klicken Sie auf den Namen Ihrer privaten App.
  • Klicken Sie neben Ihrem Zugriffstoken auf Rotieren:
    • Wenn Ihr Token kompromittiert wurde und Sie den Zugriff sofort widerrufen möchten, klicken Sie auf Rotieren und jetzt verfallen lassen.
    • Auch wenn keine unmittelbare Bedrohung für Ihr Token besteht, wird empfohlen, es alle sechs Monate zu rotieren. Wenn Sie bereit sind, ein regelmäßiges Rotieren Ihres Tokens zu initiieren, klicken Sie auf Rotieren und später verfallen lassen, wodurch das Token in 7 Tagen abläuft.
      • Wenn Ihre App schon früher umgestellt werden kann, klicken Sie auf Jetzt verfallen lassen.
      • Wenn Sie entscheiden, dass Sie mehr Zeit benötigen, können Sie auf Rotieren abbrechen klicken, wodurch das Verfallen des ursprünglichen Tokens aufgehoben wird und das neue Zugriffstoken widerrufen wird.

rotate-private-app-access-token

HubSpot sendet auch E-Mail-Benachrichtigungen an Super-Admins mit Erinnerungen an den Status der Zugriffstoken-Rotation sowie andere damit verbundene Warnungen. Super-Admins in Ihrem HubSpot-Account erhalten Benachrichtigungen für die folgenden Ereignisse und Erinnerungen:

  • Ein Super-Admin hat eine Rotation initiiert (entweder sofort oder in 7 Tagen).
  • Ein Super-Admin hat eine ausstehende Rotation abgebrochen.
  • Ein Super-Admin hat sich dafür entschieden, ein Zugriffstoken sofort verfallen zu lassen, indem er auf Jetzt verfallen lassen geklickt hat, anstatt 7 Tage auf das Verfallen des Tokens zu warten.
  • Das Zugriffstoken der App läuft in 24 Stunden ab.
  • Das Zugriffstoken der App wurde rotiert und ist nach 7 Tagen abgelaufen.
  • Wenn Sie Ihr Zugriffstoken seit über 180 Tagen nicht mehr rotiert haben, erhalten Super-Admins auch eine Erinnerungs-E-Mail, um das Zugriffstoken Ihrer App zu rotieren.

API-Aufrufprotokolle anzeigen

So überprüfen Sie die API-Aufrufe, die Ihre App in den letzten 30 Tagen durchgeführt hat:

  • Klicken Sie auf der Detailseite Ihrer App auf die Registerkarte Protokolle.
  • Überprüfen und filtern Sie die API-Aufrufe Ihrer privaten App:
    • Klicken Sie auf die Dropdown-Menüs Methode und Antwort, um Ihre historischen API-Aufrufe nach Anfragemethode oder Antwortcode zu filtern.
    • Klicken Sie auf das Dropdown-Menü für das Startdatum oder das Enddatum, um Ihre Aufrufprotokolle auf einen bestimmten Zeitraum einzugrenzen.
    • Sie können auch über das Suchfeld Suche nach Anfrage-URL nach bestimmten Aufrufen suchen.

private-app-logs-tab-updated

  • Um die API-Aufrufprotokolle zu exportieren, klicken Sie auf Protokolle exportieren (CSV). Geben Sie dann einen Datumsbereich (bis zu den letzten 30 Tagen) an und klicken Sie auf Exportieren.
  • Wählen Sie im Pop-up-Feld den Datumsbereich der API-Aufrufe aus, die Sie exportieren möchten, und klicken Sie auf Exportieren. Sie erhalten eine E-Mail mit einem Download-Link, sobald der Export zum Download bereitsteht. 

Limits für private Apps

Sie können bis zu 20 private Apps in Ihrem HubSpot-Account erstellen. Jede private App unterliegt den Richtlinien zur API-Nutzung von HubSpot. Die Anzahl der Aufrufe, die Ihre private App durchführen kann, hängt von Ihrem Account-Abonnement ab und davon, ob Sie das API-Add-on erworben haben:

  Produktstufe Pro 10 Sekunden Pro Tag
Private Apps

(Jede Version)

Kostenlose Version und Starter

100/private App 250.000/Account
 

(Jede Version)

Pro und Enterprise

150/private App 500.000/Account
Private Apps mit API-Add-on

(Jede Version)

Kostenlose Version, Starter, Professional und Enterprise

200/private App 1.000.000/Account

Wenn Sie sowohl eine Starter- als auch eine Professional-Version haben, gelten für Ihren Account Limits für die höhere Stufe (Professional).

Sie können eine GET-Anfrage an /account-info/v3/api-usage/daily/private-apps durchführen, um die tägliche API-Nutzung für alle privaten Apps in Ihrem HubSpot-Account zu überprüfen. Erfahren Sie mehr über die Verwendung der Account-Informationen-API.

Eine private App löschen

Wenn Sie eine Ihrer privaten Apps löschen, wird ihr Zugriffstoken dauerhaft widerrufen und Sie können sie nicht mehr für API-Aufrufe verwenden.

So löschen Sie eine App:

  • Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf das Zahnradsymbol.
  • Klicken Sie auf den Namen Ihrer privaten App.
  • Klicken Sie unten auf der Seite auf [Name Ihrer App] löschen.
  • Geben Sie im Dialogfeld den Namen Ihrer App ein, um deren Löschung zu bestätigen, und klicken Sie dann auf Löschen.

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.