Letzte Änderung: 28. August 2025
OAuth ist eine sichere Authentifizierungsmethode, die Autorisierungstoken anstelle eines Passworts verwendet, um Ihre App mit einem Kunden-Account zu verknüpfen. Das Initiieren von OAuth-Zugriff ist der erste Schritt, um Benutzern das Installieren Ihrer App in ihren HubSpot-Accounts zu ermöglichen.

​
Hinweis:

  • Jede App, die für die Installation durch mehrere HubSpot-Accounts oder für ein Listing im App Marketplace entwickelt wurde, muss OAuth verwenden.
  • Benutzer, die Apps in ihrem HubSpot-Account installieren, müssen entweder ein Super-Admin sein oder über Berechtigungen für Zugriff auf den App-Marketplace verfügen.

​
Empfohlene Ressourcen

  • Die OAuth-Schnellanleitung ermöglicht Ihnen mithilfe einer Arbeitsbeispiel-App einen schnellen Einstieg.
  • Dieses HubSpot Academy-Tutorial bietet eine schnelle Einführung in die Verwendung von OAuth mit HubSpot, einschließlich einer ausführlichen Darstellung des HubSpot-OAuth-Prozesses und der Aktualisierung eines Zugriffstokens.

​
OAuth-Authentifizierung einrichten

So richten Sie die OAuth-Authentifizierung für Ihre App ein:
  • Zuerst müssen Sie eine App erstellen in einem HubSpot-Entwickler-Account. Nach dem Erstellen der App finden Sie die Client-ID und das Client-Geheimnis der App auf der Seite zur Authentifizierung Ihrer App-Einstellungen.
MyHubSpotApp
  • Verwenden Sie die Client-ID und das Client-Geheimnis zusammen mit den unten beschriebenen Abfrageparametern und Bereichen, um Ihre Autorisierungs-URL zu erstellen.
  • Leiten Sie Benutzer, die Ihre App installieren, zur Autorisierungs-URL weiter, wo ihnen ein Bildschirm angezeigt wird, auf dem sie ihren Account auswählen können und Zugriff auf Ihre Integration gewährt werden kann. Sie können die Autorisierungs-URL für einen bestimmten HubSpot-Account festlegen, indem Sie die Account-ID zwischen /oauth/ und /authorize hinzufügen, wie unten gezeigt. Nachdem Sie Zugriff gewährt haben, gelangen sie über eine redirect_url, der ein Code-Abfrageparameter angehängt ist, zurück zu Ihrer Anwendung. Sie verwenden diesen Code und das Client-Geheimnis, um ein access_token und refresh_token von HubSpot zu erhalten.
    • Beispiel-Autorisierungs-URLs
      • Alle Accounts: https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
      • Spezifischer Account (ID 123456): https://app.hubspot.com/oauth/123456/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
    • Beispiel-Weiterleitungs-URL: https://example.com/?code=xxxx
    • Beispielfehler: https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
  • Verwenden Sie access_token, um API-Aufrufe zu authentifizieren, die für diesen HubSpot-Account vorgenommen wurden.
  • Nachdem das access_token abgelaufen ist, verwenden Sie das refresh_token, mum ein neues access_token zu generieren.

​
Hinweis:

  • Ihre App wird nicht als verknüpfte App im Account eines Benutzers angezeigt, es sei denn, Sie generieren das Aktualisierungstoken und das Token für den ersten Zugriff.
  • Zugriffstoken spiegeln die von der App angeforderten Bereiche wider. Sie spiegeln nicht die Berechtigungen oder Einschränkungen dessen wider, was ein Benutzer in seinem HubSpot-Account tun kann. Wenn beispielsweise ein Benutzer die Berechtigung hat, nur eigene Kontakte anzuzeigen, aber eine Anfrage für den crm.objects.contacts.read-Bereich autorisiert, kann das resultierende Zugriffstoken alle Kontakte im Account anzeigen und nicht nur die, die dem autorisierenden Benutzer gehören.

​
Abfrageparameter

Die folgenden Abfrageparameter sind erforderlich, wenn Sie eine Autorisierungs-URL für Ihre App erstellen:
ParameterBeschreibungAnwendung
client_idEine ID, die als eindeutige ID für Ihre App dient.Sie erhalten diese von der Seite mit den Authentifizierungseinstellungen Ihrer App (wie oben beschrieben).
redirect_uriDie URL, zu der Besucher weitergeleitet werden, nachdem Zugriff auf Ihre App gewährt wurde.Sie bestimmen diese ebenfalls auf der Seite mit den Authentifizierungseinstellungen Ihrer App. Hinweis: Aus Sicherheitsgründen muss diese URL https zur Produktion verwenden. (Beim Testen mithilfe von localhostlocalhost kann http verwendet werden.) Sie müssen auch eine Domain verwenden, da IP-Adressen nicht unterstützt werden.
scopeEin durch Leerzeichen getrennter Satz an Berechtigungen, auf die Ihre App Zugriff benötigt.Alle Bereiche, die Sie in den Einstellungen zur Authentifizierung Ihrer App aktiviert haben, werden als erforderlich behandelt. Sie müssen sie in diesem Parameter berücksichtigen oder die Autorisierungsseite zeigt einen Fehler an. Benutzern wird außerdem ein Fehler angezeigt, wenn sie versuchen, Ihre App in einem Account zu installieren, der keinen Zugriff auf einen berücksichtigten Bereich hat. Weitere Informationen darüber, welche Endpunkte durch spezifische Bereiche aufgerufen werden können, finden Sie in der Referenzdokumentation für Bereiche.
Die folgenden Parameter sind optional:
ParameterAnwendungBeschreibung
optional_scopeEin durch Leerzeichen getrennter Satz an optionalen Berechtigungen für Ihre App.Optionale Bereiche werden automatisch aus der Autorisierungsanforderung ausgeschlossen, wenn der Benutzer einen HubSpot-Account auswählt, der keinen Zugriff auf dieses Tool hat (z. B. Autorisierung eines Content Hub-Enterprise-Bereichs in einem kostenlosen HubSpot-Account). Wenn Sie optionale Bereiche verwenden, müssen Sie das Zugriffstoken und das Aktualisierungstoken überprüfen, um zu sehen, welche gewährt wurden. Weitere Informationen finden Sie in der Referenzdokumentation zu Bereichen.
stateWenn dieser Parameter in der Autorisierungs-URL enthalten ist, wird der Wert in einem state-Abfrageparameter berücksichtigt, wenn der Benutzer zur redirect_uri weitergeleitet wird.Ein Zeichenfolgenwert, der zur Aufrechterhaltung des Status des Benutzers verwendet werden kann, wenn er zurück zu Ihrer App weitergeleitet wird.

​
Bereiche konfigurieren

OAuth erfordert, dass Sie Bereiche, oder Berechtigungen, für Ihre App festlegen. Jeder Bereich bietet Zugriff auf eine Reihe von HubSpot-API-Endpunkten und ermöglicht Benutzern, Ihrer App Zugriff auf bestimmte Tools in ihrem HubSpot-Account zu gewähren.
granular-scopes-selection
Der Zugriff auf bestimmte APIs oder Endpunkte hängt von der HubSpot-Account-Stufe ab. Wenn Ihre App mit mehreren Typen von HubSpot-Accounts arbeitet, können Sie den optional_scope-Parameter verwenden, um alle Stufen-Bereiche zu bierücksichtigen, mit denen Sie arbeiten. Auf diese Weise können Kunden, die kostenlose HubSpot-Accounts verwenden, weiterhin Ihre App autorisieren, selbst wenn sie nicht auf alle ihre Bereiche Zugriff haben. Ihre App muss auf alle Bereiche überprüfen, für die sie nicht autorisiert wird, und diese verarbeiten. Eine vollständige Liste der Bereiche finden Sie hier.

​
Verwandte Dokumente

Authentifizierungsmethoden in HubSpot OAuth-Schnellanleitung Verwalten von Token