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. 
  • 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.

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. 
  • 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 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
cms.domains.read Integratoren können CMS-Domains im Account eines Kunden listen.  CMS-API Alle Accounts
cms.domains.write Integratoren können benutzerdefinierte CMS-Domains erstellen, aktualisieren und löschen.  CMS-API Alle Accounts
cms.functions.read Integratoren können alle serverlosen CMS-Funktionen, alle damit verbundenen Geheimnisse und Funktionsausführungsergebnisse anzeigen.  CMS-API CMS Hub Enterprise
cms.functions.write Integratoren können serverlose CMS-Funktionen und CMS-Geheimnisse schreiben. CMS-API CMS Hub Enterprise
cms.knowledge_base.articles.read Zeigen Sie Details zu Wissensdatenbankartikeln an. CMS-API Service Hub Professional oder Enterprise 

cms.knowledge_base.articles.write

 Gewährt Zugriff auf aktualisierte Wissensdatenbankartikel.  CMS-API Service Hub Professional oder Enterprise
cms.knowledge_base.articles.publish Gewährt Zugriff auf das Aktualisieren und Veröffentlichen von Wissensdatenbankartikeln. CMS-API Service Hub Professional oder Enterprise
cms.knowledge_base.settings.read Zeigen Sie allgemeine Einstellungen sowie Vorlageneinstellungen für Wissensdatenbanken an, z. B. die Domain oder die Haupt-UR. CMS-API Service Hub Professional oder Enterprise
cms.knowledge_base.settings.write Gewährt Zugriff auf das Aktualisieren der allgemeinen Einstellungen sowie der Vorlageneinstellungen für Wissensdatenbanken. Dazu gehört auch der Schreibzugriff auf Wissensdatenbankartikel. CMS-API Service Hub Professional oder Enterprise
cms.performance.read Integratoren können CMS-Performance-Daten für alle Ihre Websites anzeigen. CMS-API Alle Accounts
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.custom.read Zeigen Sie Details zu benutzerdefinierten Objekten im HubSpot CRM an. Endpunkte für benutzerdefinierte Objekte Alle Enterprise-Accounts
crm.objects.custom.write Erstellen oder löschen Sie benutzerdefinierte Objekte im HubSpots CRM oder nehmen Sie Änderungen an diesen vor.  Endpunkte für benutzerdefinierte Objekte Alle Enterprise-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.feedback_submission.read Zeigen Sie Details zu den Einsendungen zu einer Ihrer Feedback-Umfragen an. Feedback-Umfrage-Endpunkte Service Hub Professional oder Enterprise
crm.objects.goals.read Zeigen Sie alle Zieltypen an.  Ziele-Endpunkte Sales Hub Starter, Professional oder Enterprise
crm.objects.line_items.read Zeigen Sie Eigenschaften und andere Details zu Artikeln an. Artikel-Endpunkte Alle Accounts
crm.objects.line_items.write Erstellen, löschen oder ändern Sie Artikel.  Artikel-Endpunkte Alle Accounts
crm.objects.marketing_events.read Zeigen Sie Details zu Marketingevents an.  Marketingevents-Endpunkte Alle Accounts
crm.objects.marketing_events.write Erstellen, löschen oder ändern Sie Marketingevents.  Marketingevents-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.objects.quotes.read Zeigen Sie Eigenschaften und andere Details zu Angeboten und Angebotsvorlagen an. Angebote-Endpunkte Alle Accounts
crm.objects.quotes.write Erstellen, löschen oder ändern Sie Angebote. Angebote-Endpunkte 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.custom.read Zeigen Sie Details zu benutzerdefinierten Objektdefinitionen im HubSpot CRM an. Endpunkte für benutzerdefinierte Objekte Alle Enterprise-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
crm.schemas.line_items.read Zeigen Sie Details zu Artikeln an. Artikel-Endpunkte Alle Accounts
crm.schemas.quotes.read Zeigen Sie Details zu Angeboten und Angebotsvorlagen an. Angebote-Endpunkte Alle Accounts
settings.billing.write Nehmen Sie Änderungen an den Abrechnungseinstellungen Ihres Accounts vor. Dies umfasst das Verwalten und Zuweisen von kostenpflichtigen Lizenzen für Benutzer. Einstellungen-Endpunkte Alle Accounts
settings.currencies.read Liest vorhandene Wechselkurse zusammen mit der aktuellen Unternehmenswährung, die Ihrem Portal zugeordnet ist.  Account-Informationen-Endpunkte Alle Accounts
settings.currencies.write Erstellen, aktualisieren und löschen Sie Wechselkurse und aktualisieren Sie die mit Ihrem Portal verknüpfte Unternehmenswährung.  Account-Informationen-Endpunkte Alle Accounts
settings.users.read Zeigen Sie Details zu Account-Benutzern und deren Berechtigungen an. Benutzereinrichtung-Endpunkte Alle Accounts
settings.users.write Verwalten Sie Benutzer und Benutzerberechtigungen in Ihrem HubSpot-Account. Dies umfasst das Erstellen neuer Benutzer, das Zuweisen von Berechtigungen und Rollen sowie das Löschen bestehender Benutzer.  Benutzereinrichtung-Endpunkte Alle Accounts
settings.users.teams.read Erfahre mehr über die Teams des Accounts.  Benutzereinrichtung-Endpunkte Alle Accounts
settings.users.team.write Weisen Sie den Teams in Ihrem HubSpot-Account Benutzer zu.  Benutzereinrichtung-Endpunkte Alle Accounts
account-info.security.read Beinhaltet den Zugriff auf Account-Aktivitätsprotokolle und andere Account-Sicherheitsinformationen.  Account-Aktivitäten-API Alle Accounts
accounting Ermöglicht HubSpot und der Buchhaltungsintegration das Teilen von Rechnungs-, Produkt- und Kontaktdetails. Buchhaltungserweiterung-API Alle Accounts
actions Fügen Sie Formulare zu den Seiten des Kontakts hinzu, die benutzerdefinierte Aktionen ausführen. CRM-Erweiterungen-API Alle Accounts
analytics.behavioral_events.send Beinhaltet Zugriff auf das Senden von benutzerdefinierten verhaltensorientierten Events.  Analytics-API Marketing Hub Enterprise
automation Umfasst Workflows. Automatisierungs-API (Workflows-Endpunkte) Marketing Hub Professional oder Enterprise
behavioral_events.event_definitions.read_write Erstellen, lesen, aktualisieren oder löschen Sie verhaltensorientierte Events. Dies umfasst verhaltensorientierte Event-Eigenschaften.  Analytics-API Marketing Hub Enterprise
business_units.view.read Zeigen Sie Unternehmensbereichsdaten einschließlich Logo-Informationen an. Unternehmensbereiche-API Unternehmensbereiche-Add-on
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
communication_preferences.read Zeigen Sie Details zu den Abo-Einstellungen Ihrer Kontakte an.  Abo-Einstellungen-API Alle Accounts
communication_preferences.read_write Melden Sie Kontakte für Ihre Abonnementtypen an bzw. von diesen ab. Es werden keine Kontakte für ein Abonnement angemeldet, die sich abgemeldet haben.  Abo-Einstellungen-API Alle Accounts
communication_preferences.write Melden Sie Kontakte für Ihre Abonnementtypen an bzw. von diesen ab. Es werden keine Kontakte für ein Abonnement angemeldet, die sich abgemeldet haben.  Abo-Einstellungen-API Alle Accounts
content Umfasst Websites, Landingpages, 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
conversations.write Senden Sie Nachrichten in Konversationen. Erstellen und aktualisieren Sie Nachrichten-Threads. Conversations-Postfach- und Nachrichten-API Alle Accounts
crm.export Exportieren Sie Datensätze aus Ihrem CRM für alle CRM-Datentypen. CRM-Exporte-API  Alle 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
ctas.read Ermöglicht Lesezugriff für CTAs. Keine publicAPI verfügbar Marketing Hub oder CMS Hub Starter, 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.
external_integrations.forms.access Umfasst die Möglichkeit, vorhandene Formulare umzubenennen, zu löschen und zu klonen. Formulare-Endpunkte

Alle Accounts
files Umfasst den Zugriff auf den Datei-Manager. Dateien (Datei-Manager) und Datei-Mapper (CMS-Vorlagen, Module und Layout) Alle Accounts
files.ui_hidden.read Zeigen Sie Details an oder laden Sie Benutzerdateien, Anhänge und Systemdateien von allen HubSpot-Tools herunter.  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
media_bridge.read Gewährt Zugriff auf Events und Objekte von der Media Bridge aus. Media-Bridge-API Alle Accounts
media_bridge.write Gewährt Zugriff auf das Erstellen und Aktualisieren von Events und Objekten über die Media Bridge. Media-Bridge-API Alle Accounts
oauth Grundlegender Bereich, der für OAuth erforderlich ist. Dieser Bereich wird standardmäßig allen Apps hinzugefügt.   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
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

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.