Migrate an API key integration to a private app

Wenn Sie in Ihrem Account ein Banner zur Deaktivierung Ihres API-Schlüssels sehen:

  • Die API-Schlüssel für Entwickler sind von den Standard-API-Schlüsseln von HubSpot getrennt und werden nicht eingestellt. Entwickler-API-Schlüssel werden für die Verwaltung von Einstellungen im Zusammenhang mit Ihren HubSpot-Apps verwendet, einschließlich Webhooks-API-Abonnements und Chronik-Events-API-Event-Typen.

Wenn Sie eine interne Integration erstellt haben, die einen HubSpot-API-Schlüssel verwendet, bietet Ihr API-Schlüssel sowohl Lese- als auch Schreibzugriff auf alle Ihre HubSpot-CRM-Daten. Dies kann ein Sicherheitsrisiko darstellen, wenn Ihr API-Schlüssel kompromittiert wird. Durch die Migration zu einer privaten App können Sie die spezifischen Bereiche autorisieren, die Ihre Integration erfordert. Dadurch wird ein Zugriffstoken generiert, das die Daten begrenzt, die Ihre Integration in Ihrem Account anfragen oder ändern kann.

Befolgen Sie die Schritte unten, um eine vorhandene Integration mit API-Schlüssel zu einer privaten App zu migrieren. Es wird empfohlen, zuerst eine Testumgebung zu verwenden, z. B. einen Entwickler-Test-Account oder einen Sandboxk-Account, bevor Sie Änderungen in der Produktion vornehmen. Wenn Sie während der Migration Ihrer App Fragen haben, besuchen Sie die Entwickler-Community. 

Eine Videoanleitung zum Migrieren einer API-Schlüsselintegration zu einer privaten App finden Sie im HubSpot-Entwickler-Video unten:

In diesem Leitfaden

Bitte beachten: Private Apps unterstützen nicht Webhooks und bestimmte Typen von Erweiterungen. Wenn Ihre vorhandene Integration eine dieser Funktionen verwendet, sollten Sie stattdessen mithilfe von OAuth eine öffentliche App erstellen.

Eine neue 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.
  • Wählen Sie als Nächstes die Bereiche aus, die basierend auf den von Ihrer Integration verwendeten APIs autorisiert werden sollen. So finden Sie heraus, welche Bereiche Ihre App benötigt:
    • Stellen Sie eine Liste der HubSpot-APIs zusammen, die Ihre vorhandene Integration verwendet.
    • Gehen Sie für jede API-Anfrage zur zugehörigen Entwicklerdokumentation (z. B. zu der für die Kontakte-API).
    • Klicken Sie auf die Registerkarte Endpunkte und scrollen Sie dann zu dem Endpunkt, den Ihre Integration verwendet.
    • Suchen Sie im Abschnitt Anforderungen die Bereiche, die für die Verwendung des Endpunkts erforderlich sind. Wenn möglich, sollten Sie sich für die unter Granulare Bereich(e) aufgeführten Bereiche entscheiden, und nicht für die unter Standardbereich(e). Wenn keine granularen Bereiche aufgeführt sind, verwenden Sie die Standardbereiche.locate-scope-in-endpoints-tab-for-private-app-migration
    • Gehen Sie zurück zu den Einstellungen für Ihre private App und aktivieren Sie die Kontrollkästchen Lesen oder Schreiben neben den entsprechenden Bereichen. Sie können auch über die Suchleiste Bereich suchen nach einem Bereich suchen.select-matching-scope-for-private-app
  • Nachdem Sie Ihre Bereiche ausgewählt haben, klicken Sie oben rechts auf App erstellen. Sie können jederzeit Änderungen an Ihrer App vornehmen, nachdem Sie diese erstellt haben.
  • Überprüfen Sie im Dialogfeld die Informationen zum Zugriffstoken Ihrer App und klicken Sie dann auf Mit dem Erstellen fortfahren.

Wenn Ihre private App erstellt ist, können Sie mithilfe von ihrem Zugriffstoken API-Anfragen erstellen. Klicken Sie auf der Registerkarte Details auf der Einstellungsseite Ihrer privaten App unter Ihrem Zugriffstoken auf Token anzeigen, um es zu enthüllen.

show-private-app-access-token-migration-guide

Die Autorisierungsmethode der API-Anfragen Ihrer Integration aktualisieren

Anstatt einen hapiKey-Abfrageparameter zu verwenden, um API-Anfragen durchzuführen, werden Zugriffstoken von privaten Apps im Authorization-Header Ihrer Anfrage aufgenommen. Legen Sie bei einer Anfrage den Wert des Authorization-Headers auf Bearer YOUR_ACCESS_TOKEN fest. Sofern nicht anders angegeben, ist diese Autorisierungsmethode mit allen öffentlichen API-Endpunkten kompatibel, einschließlich der in der HubSpot-Legacy-Entwicklerdokumentation aufgeführten Legacy-APIs.

Ihre Anfrage kann wie folgt aussehen:

axios.get('https://api.hubapi.com/crm/v3/objects/contacts', { headers: { 'Authorization': `Bearer ${YOUR_ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );$headers = [ 'Content-Type: application/json', 'Authorization: Bearer ' . YOUR_ACCESS_TOKEN, ]; $curl = curl_init(); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); curl_setopt($curl, CURLOPT_URL, 'https://api.hubapi.com/crm/v3/objects/contacts'); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $contacts = curl_exec($curl); curl_close($curl); var_dump($contacts);require 'uri' require 'net/http' require 'openssl' url = URI("https://api.hubapi.com/crm/v3/objects/contacts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Get.new(url) request['content-type'] = 'application/json' token = 'YOUR_ACCESS_TOKEN' request['authorization'] = "Bearer #{token}" response = http.request(request) puts response.read_bodyimport requests url = "https://api.hubapi.com/crm/v3/objects/contacts" headers = { 'content-type': 'application/json', 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } response = requests.request("GET", url, headers=headers) print(response.text)

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 }); $hubSpot = \HubSpot\Factory::createWithAccessToken('access-token'); $response = $hubSpot->crm()->contacts()->basicApi()->getPage();# Load the gem require 'hubspot-api-client' # Setup client client = Hubspot::Client.new(access_token: 'YOUR_ACCESS_TOKEN') # Get contacts contacts = client.crm.contacts.basic_api.get_pagefrom hubspot import HubSpot api_client = HubSpot(access_token='YOUR_ACCESS_TOKEN') api_client.crm.contacts.get_page()

Um die Migration zu Ihrer privaten App abzuschließen, entfernen Sie alle Verweise auf den HubSpot-API-Schlüssel aus Ihrem Code und verwenden Sie stattdessen den oben genannten Ansatz, um das Zugriffstoken Ihrer privaten App zu verwenden. Abhängig von der Anfrage, die Sie durchzuführen, sollten Sie ein Geheimnis erstellen, um Ihr Token zu speichern, anstatt es in Ihren Anfragen zu programmieren. Die Verwendung eines Geheimnisses verhindert, dass Ihr Token offengelegt wird, z. B. wenn ein Token in einer serverlosen Funktion verwendet wird. So speichern Sie das Zugriffstoken als Geheimnis:

  • Führen Sie im Terminal hs secrets add secretName aus. Es wird empfohlen, dem Geheimnis einen einfachen Namen zu geben, damit Sie in Zukunft leicht darauf verweisen können.
  • Fügen Sie das Zugriffstoken in das Terminal ein und drücken Sie dann die Eingabetaste.

Sie können dann auf Ihr Geheimnis als Umgebungsvariable zugreifen. Erfahren Sie mehr dazu im folgenden Beispiel für serverlose Funktionen.

Um zu bestätigen, dass alle Verweise auf Ihren API-Schlüssel entfernt wurden, können Sie das Aufrufprotokoll in Ihrem HubSpot-Account überprüfen:

  • Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf das Zahnradsymbol.
  • Gehen Sie in der linken Seitenleiste zu Integrationen > API-Schlüssel.
  • Überprüfen Sie auf der Registerkarte API-Aufrufe die letzten Anfragen, um zu bestätigen, dass seit dem Entfernen aller vorherigen Verweise keine neuen Anfragen durchgeführt wurden, um das Zugriffstoken Ihrer privaten App zu verwenden.

check-api-key-call-log-after-migration

Wenn Sie einen kostenpflichtigen Marketing Hub-Account mit Marketingkontakten haben und Sie zuvor Kontakte festgelegt haben, die durch Integrationen mit Ihrem API-Schlüssel als Marketingkontakte erstellt wurden, müssen Sie dies auch für Ihre private App tun:

  • Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf das Zahnradsymbol.
  • Gehen Sie in der linken Seitenleiste zu Integrationen > Marketingkontakte.
  • Verwenden Sie unter Ihre verknüpften Apps die Suchleiste, um Ihre private App zu suchen, und klicken Sie dann auf den Schalter Aktivieren, um Kontakte als Marketingkontakte zu synchronisieren, um ihn zu aktivieren.

set-private-app-contacts-as-marketing-contacts

Nachdem Sie die Einrichtung Ihrer privaten App abgeschlossen haben und bestätigt haben, dass alle Verweise auf Ihren API-Schlüssel in Ihrem Code entfernt wurden, können Sie den Schlüssel deaktivieren.

Anfragen überprüfen und Protokolle überwachen

Nachdem Sie alle Verweise auf den HubSpot-API-Schlüssel in Ihrem Code entfernt und stattdessen durch Verweise auf das Zugriffstoken Ihrer privaten App ersetzt haben, sind keine weiteren Änderungen am Code erforderlich.

Wenn Sie die oben beschriebenen Schritte in einem Entwickler-Test- oder Sandbox-Account befolgt haben, wiederholen Sie denselben Vorgang in Ihrem Produktions-Account. Überwachen Sie dann die API-Aufrufprotokolle Ihrer privaten App und bestätigen Sie, dass keine Ihrer App-Anfragen 400-Fehler zurückgibt:

  • 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 den Namen Ihrer privaten App.
  • Klicken Sie auf die Registerkarte Protokolle.
  • Eine nicht erfolgreiche API-Anfrage, die aufgrund eines fehlenden Bereichs fehlgeschlagen ist, wird als 403-Fehler angezeigt. Wenn Sie die Laufzeitprotokolle Ihrer Integration aufrufen, sollte die Antwort aus der entsprechenden API-Anfrage eine Fehlermeldung mit Details zu fehlenden Bereichen enthalten.

403-error-after-private-app-migration

  • Wenn Sie einen neuen Bereich für Ihre private App hinzufügen müssen:
    • Klicken Sie auf die Registerkarte Details.
    • Klicken Sie auf Details bearbeiten.
    • Klicken Sie oben auf der Seite auf Bereiche.
    • Aktivieren Sie das Kontrollkästchen neben allen fehlenden Bereichen und klicken Sie dann oben rechts auf Änderungen übernehmen, wenn Sie fertig sind.

select-missing-scope-private-app-migration

Erfahren Sie im Leitfaden für private Apps mehr über das Erstellen und Verwalten von privaten Apps und deren Obergrenzen.

Implementierungsbeispiele

Im Folgenden erfahren Sie, wie Sie häufig verwendete API-Schlüssel verwenden und wie Sie stattdessen zu Zugriffstoken für private Apps migrieren.

Serverlose Funktionen

Wenn Sie einen API-Schlüssel innerhalb einer serverlosen Funktion verwenden, können Sie das Zugriffstoken der privaten App ebenfalls zur Authentifizierung verwenden. Sie müssen sicherstellen, dass die private App über die Bereiche verfügt, die die Funktion ausführen muss. 

So authentifizieren Sie eine serverlose Funktion mit dem Zugriffstoken einer privaten App:

  • Klicken Sie auf der Karte Zugriffstoken auf Token anzeigen , um Ihr Zugriffstoken zu enthüllen. Klicken Sie dann auf Kopieren, um das Token in Ihre Zwischenablage zu kopieren.
    show-private-app-access-token-1
  • Erstellen Sie mit kopiertem Zugriffstoken ein neues Geheimnis, um das Token zu speichern:
    • Führen Sie im Terminal hs secrets add secretName aus. Es wird empfohlen, dem Geheimnis einen einfachen Namen zu geben, damit Sie in Zukunft leicht darauf verweisen können.
    • Fügen Sie das Zugriffstoken in das Terminal ein und drücken Sie dann die Eingabetaste.
  • Fügen Sie in der serverless.json-Datei Ihrer serverlosen Funktion den Geheimnisnamen zum secrets-Array hinzu:
// example serverless.json file { "runtime": "nodejs18.x", "version": "1.0", "secrets": ["secretName"], "endpoints": { "getPrompts": { "method": "GET", "file": "serverlessFunction.js" } } }
  • Legen Sie in der JavaScript-Datei Ihrer serverlosen Funktion den Wert des Authorization-Headers auf Bearer secretName fest. Wenn Sie zum Beispiel die Kontakte-API mithilfe von Node.js und axios aufrufen, würde die Anfrage wie folgt aussehen:
// example serverless function const axios = require('axios'); exports.main = (context, sendResponse) => { axios.get(`https://api.hubapi.com/crm/v3/objects/contacts`, { headers: { 'Authorization': `Bearer ${process.env.secretName}`, 'Content-Type': 'application/json' } } ) sendResponse({statusCode: 200}); };

Erfahren Sie mehr über das Durchführen von API-Aufrufen mit dem Token Ihrer App.

Einmalige Aufgaben

Wenn Sie einen API-Schlüssel zum Ausführen von einmaligen Aufgaben verwenden, z. B. zum Erstellen einer Eigenschaft, können Sie stattdessen eine private App erstellen und das Zugriffstoken verwenden, um den Aufruf zu authentifizieren. Sobald eine private App erstellt wurde, können Sie ihr Zugriffstoken für einmalige Aufgaben wiederverwenden, solange die private App über die entsprechenden Bereiche verfügt. Sie können die Bereiche einer privaten App jederzeit über die Einstellungen der privaten App in HubSpot aktualisieren. Sie können auch die private App löschen und eine neue erstellen, die spezifisch für die auszuführende Aufgabe ist.

private-app-edit-scopes

Benutzerdefinierte Objekte erstellen

Anstatt einen API-Schlüssel zum Erstellen eines benutzerdefinierten Objekts zu verwenden, können Sie stattdessen eine private App erstellen und, sofern die App über die erforderlichen Bereiche verfügt, den Aufruf mithilfe von ihrem Zugriffstoken authentifizieren Wenn Sie beispielsweise Postman zum Erstellen eines benutzerdefinierten Objekts verwenden, legen Sie den Autorisierungstyp auf Bearer-Token fest und geben Sie dann im Feld Token das Token ein.

postman-private-app-access-token-field

Erfahren Sie im Entwicklerblog von HubSpot mehr über das Erstellen eines benutzerdefinierten Objekts mithilfe einer privaten App.

Workflow-Aktionen mit benutzerdefiniertem Code

Wenn Sie einen API-Schlüssel in einer Workflow-Aktion mit benutzerdefiniertem Code verwenden, können Sie stattdessen das Zugriffstoken der privaten App verwenden, sofern die App über die erforderlichen Bereiche verfügt. Um die Aktualisierung durchzuführen, öffnen Sie die benutzerdefinierte Aktion im Workflow-Editor und führen Sie dann die folgenden Aktualisierungen durch:

const hubspotClient = new hubspot.Client({ accessToken: process.env.secretName });
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.