Letzte Änderung: 22. August 2025
Verwenden Sie die OAuth-Token-API, um Token zu generieren und zu verwalten, die für die Autorisierung Ihrer öffentlichen App und der von ihr vorgenommenen Anfragen benötigt werden. Beispielsweise müssen Sie diese API verwenden, um die Token für den erstmaligen Zugriff und die Aktualisierung während des App-Installationsprozesses abzurufen. Sie verwenden sie dann, um neue Token zu generieren, wenn die alten ablaufen. Erfahren Sie mehr über das Arbeiten mit OAuth. Bevor Sie diese Endpunkte verwenden können, müssen Sie eine öffentliche App erstellen. Ein Benutzer muss sie dann in seinem Account installieren, um OAuth-Zugriff zu initiieren.

​
Initiieren des OAuth-Zugriffs

Nach Erstellung Ihrer App kann ein Benutzer sie in seinem HubSpot-Account installieren. Er verwendet die Installations-URL in den Einstellungen Ihrer App, die die client_id, redirect_uri und scopes als Abfrageparameter enthält. Sie können bei Bedarf auch optional_scopes und state einbeziehen. Nachdem ein Benutzer Ihre App autorisiert und in seinem Account installiert hat, wird der Weiterleitungs-URL ein code-Wert hinzugefügt, mit dem Sie ein Zugriffstoken und eine Aktualisierungstoken generieren können. Das Zugriffstoken wird verwendet, um Anfragen zu authentifizieren, die Ihre App stellt, während das Aktualisierungstoken verwendet wird, um ein neues Zugriffstoken abzurufen, wenn das aktuelle abläuft. Erfahren Sie mehr über das Initiieren von OAuth für Ihre App.

​
Token für erstmaligen Zugriff und Aktualisierung generieren

Um OAuth-Zugriffs- und Aktualisierungstoken zu abzrufen, führen Sie eine im URL-Format codierte POST-Anfrage an /oauth/v1/token durchzuführen. Geben Sie im Anfragetext verschiedene Authentifizierungsparameter an, z. B. client_id und client_secret, zusammen mit dem über die Weiterleitungs-URL zurückgegebenen code-Parameter. Nachdem ein Benutzer Ihre App autorisiert hat, wird der Weiterleitungs-URL ein code-Wert hinzugefügt. Mit diesem Code generieren Sie das Token für den erstmaligen Zugriff und das Aktualisierungstoken . Zugriffstoken sind kurzlebig, und Sie können den expires_in-Parameter beim Generieren eines Zugriffstoken überprüfen, um seine Lebensdauer (in Sekunden) zu bestimmen. Ihre Anfrage kann beispielsweise wie folgt aussehen: 
curl --request POST \
  --url https://api.hubapi.com/oauth/v1/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&code=bcf33c57-dd7a-c7eb-4179-9241-e01bd&redirect_uri=https://www.domain.com/redirect&client_id=7933b042-0952-4e7d-a327dab-3dc&client_secret=7a572d8a-69bf-44c6-9a34-416aad3ad5'
ParameterTypBeschreibung
grant_typeZeichenfolgeMuss authorization_code für die Anfrage sein, um Token für erstmaligen Zugriff und Aktualisierungs zu generieren.
codeZeichenfolgeDer in der Weiterleitungs-URL zurückgegebene code nach der Installation der App durch den Benutzer.
redirect_uriZeichenfolgeDie von der App festgelegte Weiterleitungs-URL.
client_idZeichenfolgeDie Client-ID der App.
client_secretZeichenfolgeDas Client-Geheimnis der App.
In der Antwort erhalten Sie das Zugriffstoken zusammen mit dem Aktualisierungstoken , mit dem Sie das Zugriffstoken aktualisieren können. Das expires_in-Feld gibt an, wie lange das Zugriffstoken gültig sein soll (in Sekunden). 
{
  "token_type": "bearer",
  "refresh_token": "1e8fbfb1-8e96-4826-8b8d-c8af73715",
  "access_token": "CIrToaiiMhIHAAEAQAAAARiO1ooBIOP0sgEokuLtAEaOaTFnToZ3VjUbtl46MAAAAEAAAAAgAAAAAAAAAAAACAAAAAAAOABAAAAAAAAAAAAAAAQAkIUVrptEzQ4hQHP89Eoahkq-p7dVIAWgBgAA",
  "expires_in": 1800
}

​
Ein Zugriffstoken aktualisieren

Mithilfe eines Aktualisierungstoken können Sie ein neues Zugriffstoken generieren, indem Sie eine im URL-Format codierte POST-Anfrage an /oauth/v1/token durchführen. Geben Sie im Anfragetext grant_type, client_id, client_secret und refresh_token an. 
curl --request POST \
  --url https://api.hubapi.com/oauth/v1/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token&refresh_token=1e8fbfb1-8e96-4826-8b8d-c8af73715&client_id=7933b042-0952-4e7d-a327dab-3dc&client_secret=7a572d8a-69bf-44c6-9a34-416aad3ad5'
ParameterTypBeschreibung
grant_typeZeichenfolgeMuss refresh_token sein, damit die Anfrage neue Zugriffstoken aus dem Aktualisierungstoken
generiert.
refresh_tokenZeichenfolgeDer Wert des Aktualisierungstoken
s.
client_idZeichenfolgeDie Client-ID der App.
client_secretZeichenfolgeDas Client-Geheimnis der App.

​
Zugriffstoken-Metadaten abrufen

Um Informationen zu einem OAuth-Zugriffstoken abzurufen, einschließlich des Benutzers, für den das Token erstellt wurde, und der entsprechenden Hub-ID, führen Sie eine GET-Anfrage an /oauth/v1/access-tokens/{token} durch. Sie erhalten eine Antwort mit Informationen über den Zugriffstoken des Benutzers und seinen HubSpot-Account. 
{
  "token": "CNaKSIHAAEAQAAAARiO1ooBIOP0sgEokuLtATIU5m7Kzmjj0ihJJuKFq1TcIiHCqwE6MAAAAEEAAAAAAAAAAgAIUfmerBenQwc07ZHXy6atYNNW8XCVKA25hMVIAWgBgAA",
  "user": "user@domain.com",
  "hub_domain": "meowmix.com",
  "scopes": [
    "oauth",
    "crm.objects.contacts.read",
    "crm.objects.contacts.write"
  ],
  "signed_access_token": {
    "expiresAt": 1727190403926,
    "scopes": "AAEAAAAQ==",
    "hubId": 1234567,
    "userId": 293199,
    "appId": 111111,
    "signature": "5m7ihJJuKFq1TcIiHCqwE=",
    "scopeToScopeGroupPks": "AAAAQAAAAAAAAAACAAAAAAAAAAAAAIAAAAAAA4AEAAAAAAAAAAAAAABAC",
    "newSignature": "fme07ZHXy6atYNNW8XCU=",
    "hublet": "na1",
    "trialScopes": "",
    "trialScopeToScopeGroupPks": "",
    "isUserLevel": false
  },
  "hub_id": 1234567,
  "app_id": 111111,
  "expires_in": 1754,
  "user_id": 293199,
  "token_type": "access"
}

​
Hinweis:

Es ist davon auszugehen, dass die Größe von HubSpot-Zugriffstoken im Laufe der Zeit schwankt, da die darin verschlüsselten Informationen aktualisiert werden. Damit alle Änderungen berücksichtigt werden können, empfehlen wir, bis zu 512 Zeichen für Token einzuplanen.

​
Ein Aktualisierungstoken löschen

Wenn ein Benutzer Ihre App deinstalliert, können Sie die Aktualisierungstoken löschen, indem Sie eine DELETE-Anfrage an /oauth/v1/refresh-tokens/{token} durchführen. Dadurch wird nur das Aktualisierungstoken gelöscht. Mit dem Aktualisierungstoken generierte Zugriffstoken werden nicht gelöscht. Außerdem wird dadurch die Anwendung nicht von HubSpot-Accounts deinstalliert oder die Datensynchronisierung zwischen der App und dem Account verhindert.