Arbeiten mit OAuth

OAuth ist eine sichere Authentifizierungsmethode, die Autorisierungs-Token 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 für alle App-Ersteller: Jede App, die für die Installation durch mehrere HubSpot-Accounts oder für ein Listing im App Marketplace entwickelt wurde, muss OAuth verwenden. Wenn Sie einen API-Schlüssel verwenden, wird Ihr App-Listing abgelehnt. 

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

1. Der erste Schritt für die Verwendung von OAuth besteht darin, in einem HubSpot-Entwickler-Account eine App zu erstellen. Wenn Sie dies tun, finden Sie die Client-ID und das Client-Geheimnis für Ihre App auf der Authentifizierungsseite Ihrer App-Einstellungen.

MyHubSpotApp

 

2. Verwenden Sie die Client-ID und das Client-Geheimnis zusammen mit den unten beschriebenen Abfrageparametern und Bereichen, um Ihre Autorisierungs-URL zu erstellen. 

3. Leiten Sie Benutzer, die Ihre App installieren, zur Autorisierungs-URL weiter, wo ihnen ein Bildschirm angezeigt wird, auf dem sie einen Account auswählen können (wenn sie mehrere Accounts haben) 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.example.com/

Beispiel-Weiterleitungs-URL

https://www.example.com/?code=xxxx

Beispiel-Fehler

https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error

 

4. Verwenden Sie access_token, um API-Aufrufe zu authentifizieren, die für diesen HubSpot-Account vorgenommen wurden.

5. Nachdem das access_token abgelaufen ist, verwenden Sie das refresh_token aus Schritt 3, um ein neues access_token zu generieren.


Hinweis: Ihre App wird nicht als verknüpfte App in den Integrationseinstellungen eines Benutzers angezeigt, es sei denn, Sie schließen die ersten beiden dieser Schritte ab. Sie müssen das Aktualisierungstoken und das Token für den ersten Zugriff generieren, damit die App als „verknüpft“ angezeigt wird.


Abfrageparameter

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

 

Erforderliche Parameter
Erforderlicher 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 auch 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
Optionaler 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. 

Screen Shot 2020-03-26 bei 1,1.46 0,1

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.

 

Alle Bereiche
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
contacts Umfasst Kontakte und Listen. Endpunkte für Kontakte, Unternehmen, Deals, Eigenschaften, Interaktionen und Zuständige Mitarbeiter Alle Accounts
content  Umfasst Websites, Landing-Pages, CTA, E-Mail, Blog und Kampagnen. Endpunkte für CMS-API und Kalender, E-Mail und E-Mail-Events CMS Hub Professional oder Enterprise oder Marketing Hub Professional oder Enterprise
conversations.visitor_identification.tokens.create Abruf von Identifikationstoken für authentifizierte Website-Besucher, die mit dem HubSpot-Chat-Widget interagieren. Besucheridentifikations-API Professional oder Enterprise
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 oder Marketing Hub Professional oder Enterprise
e-commerce Umfasst den Zugriff auf E-Commerce-Funktionen. Produkte- und Artikel-Endpunkte Sales Hub Professional oder Enterprise

Hinweis: Benutzern muss eine kostenpflichtige Sales Hub-Lizenz zugewiesen sein, um diesen Bereich zu autorisieren.
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

Hinweis: Der Zugriff auf Formulare erfordert außerdem den contacts-Bereich.
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 oder 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.
Sales Hub Free, Starter, Professional oder Enterprise
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 Service Hub Free, Starter, Professional oder Enterprise
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