Arbeiten mit OAuth

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.

Bitte beachten: Jede App, die für die Installation durch mehrere HubSpot-Accounts oder für ein Listing im App Marketplace entwickelt wurde, muss OAuth verwenden. 

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.

Initiieren einer Integration mit OAuth 2.0

So initiieren Sie eine Integration mit OAuth 2.0:

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. Nachdem Sie Zugriff gewährt haben, gelangen sie über eine redirect_url, der ein Code-Abfrageparameter angehängt ist, zurück zu Ihrer Anwendung. Mit diesem Code und dem Client-Geheimnis erhalten Sie ein access_token und refresh_token von HubSpot.
    • Beispiel-Autorisierungs-URL: https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.beispiel.com/
    • Beispiel-Weiterleitungs-URL:https://www.beispiel.com/?code=xxxx
    • Beispiel-Fehler: https://www.beispiel.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, um ein neues access_token zu generieren.

Bitte beachten: 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. 

Abfrageparameter

Die folgenden Parameter sind erforderlich, wenn Sie eine Autorisierungs-URL für Ihre App erstellen:

Erforderliche Parameter
Parameter Beschreibung Anwendung:
Client-ID client_id=x
In der URL verwendet		 Sie erhalten diese von der Seite mit den Authentifizierungseinstellungen Ihrer App (wie oben beschrieben).
Weiterleitungs-URL redirect_uri=x
Die 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 im Produktions-Account verwenden. (Beim Testen mithilfe von localhost kann http verwendet werden.) Sie müssen außerdem eine Domain verwenden, da IP-Adressen nicht unterstützt werden.
Bereich scope=x%20x

Ein durch Leerzeichen getrennter Satz an Berechtigungen, auf die Ihre App Zugriff benötigt. Alle Bereiche, die Sie in den Authentifizierungseinstellungen 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 dazu, welche Endpunkte durch spezifische Bereiche aufgerufen werden können, finden Sie in der Tabelle „Bereiche“.

Die folgenden Parameter sind optional:

Optionale Parameter
Parameter Anwendung: Beschreibung
Optionale Bereiche &optional_scope=x%20x Ein 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. wenn der Social-Media-Bereich in einem Nur-CRM-Portal angefordert wird). Wenn Sie optionale Bereiche verwenden, müssen Sie das Zugriffstoken und das Aktualisierungstoken überprüfen, um zu sehen, welche gewährt wurden. Weitere Informationen zu Bereichen finden Sie in der folgenden Tabelle.
Status &state=y
Wenn dieser Parameter in der Autorisierungs-URL enthalten ist, wird der Wert in einem state-Abfrageparameter berücksichtigt, wenn der Benutzer zur redirect_url weitergeleitet wird.		 Ein Zeichenfolgenwert, der zur Aufrechterhaltung des Status des Benutzers verwendet werden kann, wenn er zurück zu Ihrer App weitergeleitet wird.

Bereiche

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. In der folgenden Tabelle finden Sie eine vollständige Liste der verfügbaren Bereiche und aufrufbaren Endpunkte. 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 Nur-CRM-Accounts verwenden, weiterhin Ihre App autorisieren, selbst wenn sie nicht auf alle ihre Bereiche zugreifen können. Ihre App muss auf alle Bereiche überprüfen, für die sie nicht autorisiert wird, und diese verarbeiten.


Bereich Beschreibung Bietet Zugriff auf Erforderliche Account-Stufe
automation Umfasst Workflows. Automatisierungs-API (Workflows-Endpunkte) Marketing Hub Professional oder Enterprise
business-intelligence Umfasst Endpunkte mit Bezug zu Quellendaten und E-Mail-Funktionen. Analytics-API Alle Accounts
collector.graphql_query.execute Fragen Sie Daten aus Ihrem HubSpot-Account mithilfe des GraphQL-API-Endpunkts ab. GraphQL-API-Endpunkt CMS Hub Professional oder Enterprise
collector.graphql_schema.read Führen Sie Introspection-Abfragen über GraphQL-Anwendungsclients wie GraphiQL durch. GraphiQL und andere GraphQL-Clients von Drittanbietern CMS Hub Professional oder Enterprise
crm.lists.read Zeigen Sie Details zu Kontaktlisten an. Listen-Endpunkte Alle Accounts
crm.lists.write Erstellen oder löschen Sie Kontaktlisten oder nehmen Sie Änderungen daran vor. Listen-Endpunkte Alle Accounts
crm.objects.companies.read Zeigen Sie Eigenschaften und andere Details zu Unternehmen an. Unternehmen-Endpunkte Alle Accounts
crm.objects.companies.write Zeigen Sie Eigenschaften an und erstellen oder löschen Sie Unternehmen oder nehmen Sie Änderungen daran vor. Unternehmen-Endpunkte Alle Accounts
crm.objects.contacts.read Zeigen Sie Eigenschaften und andere Details zu Kontakten an. Kontakte-Endpunkte Alle Accounts
crm.objects.contacts.write Zeigen Sie Eigenschaften an und erstellen oder löschen Sie Kontakte oder nehmen Sie Änderungen daran vor. Kontakte-Endpunkte Alle Accounts
crm.objects.deals.read Zeigen Sie Eigenschaften und andere Details zu Deals an. Deal-Endpunkte Alle Accounts
crm.objects.deals.write Zeigen Sie Eigenschaften an und erstellen oder löschen Sie Deals oder nehmen Sie Änderungen daran vor. Deal-Endpunkte Alle Accounts
crm.objects.owners.read Zeigen Sie Details zu Benutzern an, die einem CRM-Datensatz zugewiesen sind. Endpunkte für zuständige Mitarbeiter Alle Accounts
crm.schemas.companies.read Zeigen Sie Details zu den Eigenschaftseinstellungen für Unternehmen an. Eigenschaften-Endpunkte Alle Accounts
crm.schemas.companies.write Erstellen oder löschen Sie Eigenschaftseinstellungen für Unternehmen oder nehmen Sie Änderungen daran vor. Eigenschaften-Endpunkte Alle Accounts
crm.schemas.contacts.read Zeigen Sie Details zu den Eigenschaftseinstellungen für Kontakte an. Eigenschaften-Endpunkte. Alle Accounts
crm.schemas.contacts.write Erstellen oder löschen Sie Eigenschaftseinstellungen für Kontakte oder nehmen Sie Änderungen daran vor. Eigenschaften-Endpunkte Alle Accounts
crm.schemas.deals.read Zeigen Sie Details zu den Eigenschaftseinstellungen für Deals an. Eigenschaften-Endpunkte Alle Accounts
crm.schemas.deals.write Erstellen oder löschen Sie Eigenschaftseinstellungen für Deals oder nehmen Sie Änderungen daran vor. Eigenschaften-Endpunkte Alle Accounts
content Umfasst Websites, Landingpages, CTA, E-Mail, Blog und Kampagnen. Endpunkte für CMS-API und Kalender, E-Mail und E-Mail-Events CMS Hub Professional oder Enterprise bzw. Marketing Hub Professional oder Enterprise
conversations.read Zeigen Sie Details zu Threads im Conversations-Postfach an. Conversations-Postfach- und Nachrichten-API Alle Accounts
conversations.visitor_identification.tokens.create Rufen Sie Identifikationstoken für authentifizierte Website-Besucher ab, die mit dem HubSpot-Chat-Widget interagieren. Besucheridentifikations-API Alle Professional- oder Enterprise-Accounts
crm.import Ermöglicht das Importieren von Datensätzen in Ihr CRM. Umfasst das Erstellen neuer Datensätze oder Ändern bestehender Datensätze für alle CRM-Datentypen (Kontakte, Firmen, Deal-Datensätze, Tickets usw.). Umfasst nicht das Archivieren oder Löschung von Daten. CRM-Importe-API Alle Accounts
cms.source_code.read_write Bietet die Möglichkeit, Vorlagen, Module und andere Dateien hoch- und herunterzuladen, die Entwickler benötigen, um den Code für Websites und E-Mails zu schreiben. Content-Datei-Mapper-API, CMS-Module-API, CMS-Layouts, API-Vorlagen-API CMS Hub Professional oder Enterprise bzw. Marketing Hub Professional oder Enterprise
e-commerce Umfasst den Zugriff auf E-Commerce-Funktionen. Produkte- und Artikel-Endpunkte

Alle Accounts

Hinweis: Nur Professional- und Enterprise-Accounts können diesen Bereich für die Produkte-API verwenden.
files Umfasst den Zugriff auf den Datei-Manager. Dateien (Datei-Manager) und Datei-Mapper (CMS-Vorlagen, Module und Layout) Alle Accounts
forms Umfasst den Zugriff auf die Formulare-Endpunkte. Formulare-Endpunkte Alle Accounts
forms-uploaded-files Laden Sie über ein Formular eingesendete Dateien herunter. Eine über Formulareinsendung-Endpunkt hochgeladene Datei abrufen Alle Accounts
hubdb Umfasst den Zugriff auf HubDB. HubDB-Endpunkte CMS Hub Professional oder Enterprise bzw. Marketing Hub Professional oder Enterprise mit Website-Add-on
integration-sync Erlaubt den Zugriff auf die Synchronisierungs-API, mit der die meisten CRM-Objekte synchronisiert werden können. E-Commerce-Bridge-API Alle Accounts
oauth Grundlegender Bereich, der für OAuth erforderlich ist.   Alle Accounts
sales-email-read Gewährt Zugriff für das Lesen persönlicher E-Mails, die an Kontakte gesendet werden. Interaktionen-Endpunkte

Hinweis: Dieser Bereich ist erforderlich, um den Inhalt von E-Mail-Interaktionen abzurufen. Weitere Informationen erhalten Sie im Überblick über Interaktionen.		 Alle Accounts
settings.user.read Ruft Benutzer und Benutzerrollen von einem HubSpot-Account ab. Benutzereinrichtungs-API

Alle Accounts

Hinweis: Nur Enterprise-Accounts können diesen Bereich verwenden, um Benutzerrollen abzurufen.
settings.user.teams.read Ruft Teams von einem HubSpot-Account ab. Benutzereinrichtungs-API

Alle Professional- oder Enterprise-Accounts
social Umfasst den Zugriff auf die Social-Media-Inbox. Social-Media-API Marketing Hub Professional oder Enterprise
tickets Umfasst den Zugriff auf Tickets. Tickets-Endpunkte Alle Accounts
timeline Gewährt Zugriff auf das Verwalten benutzerdefinierter Events in HubSpot CRM-Datensätzen. Dies umfasst das Erstellen oder Aktualisieren von Datensätzen. Chronik-Events-Endpunkte Alle Accounts
transactional-email Umfasst Transaktions-E-Mails und die Transaktions-E-Mails-Endpunkte. Transaktions-E-Mail-Endpunkte Marketing Hub Professional oder Enterprise mit Add-on für Transaktions-E-Mails

Verwandte Dokumente

Authentifizierungsmethoden in HubSpot

OAuth-Schnellanleitung

Verwalten von Token