> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.de/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Arbeiten mit OAuth | OAuth-Schnellanleitung

> In dieser Schnellanleitung erfahren Sie, wie Sie OAuth für Ihre App einrichten (inkl. eines Node.js-App-Beispiels).

'In dieser Schnellanleitung erfahren Sie, wie Sie OAuth für Ihre App einrichten (inkl. eines Node.js-App-Beispiels).';

<style>
  {`
    .github-link a div,
    .github-link a div p {
      display: inline;
      margin: 0;
      padding: 0;
    }
    .github-link {
      background-color: rgb(255, 255, 255);
      border-radius: 24px;
      box-shadow: rgba(0, 0, 0, 0.25) 0px 2px 4px 0px;
      padding: 5px;
      max-width: 247px;
      display: flex;
      align-items: center;
      margin-bottom: 20px;
    }
    .github-icon {
        display: inline;
        width: 24px;
        margin-right: 8px;
        flex-shrink: 0;
    }
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    `}
</style>

## Bevor Sie loslegen

Bevor Sie OAuth mit HubSpot verwenden können, müssen Sie über Folgendes verfügen:

* [Ein Entwickler-Account](https://app.hubspot.com/signup-hubspot/developers)
* [Eine App](/apps/legacy-apps/public-apps/overview), die mit Ihrem Entwickler-Account verknüpft ist Ein HubSpot-Account, um Ihre App zu installieren (Sie können einen vorhandenen Account verwenden oder - einen [Test-Account erstellen](/getting-started/account-types))

<Alert type="warning">
  Sie müssen ein [Super-Admin](https://knowledge.hubspot.com/de/user-management/hubspot-user-permissions-guide#super-admin) sein, um eine App in einem HubSpot-Account zu installieren.
</Alert>

### So funktioniert das Ganze

HubSpot unterstützt den [OAuth 2.0 Grant-Type „Autorisierungscode“](https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type), der in vier grundlegende Schritten unterteilt werden kann:

1. Ihre App öffnet ein Browser-Fenster, um den Benutzer an den HubSpot OAuth 2.0-Server weiterzuleiten.
2. Der Benutzer prüft die angeforderten Berechtigungen und gewährt der App Zugriff.
3. Der Benutzer wird mit einem Autorisierungscode in der Abfragezeichenfolge zurück zur App geleitet.
4. Die App sendet eine Anfrage an den OAuth 2.0-Server, um den Autorisierungscode gegen ein Zugriffstoken auszutauschen.

### In diesem Leitfaden

* [Schnellanleitungs-App](#quickstart-app): Eine Node.js-Demo-App, die sich beim OAuth 2.0-Server von HubSpot authentifiziert
* [Abrufen von OAuth-Token](#getting-oauth-tokens): So autorisieren Sie Ihre App bei Benutzern
* [Verwenden von OAuth-Token](#using-oauth-tokens): So erstellen Sie Abfragen mit einem Token
* [Aktualisieren von OAuth-Token](#refreshing-oauth-tokens): So verwenden Sie das von HubSpot bereitgestellte Aktualisierungstoken

<Alert type="info">
  Alle Code-Beispiele in diesem Leitfaden sind in JavaScript (Node.js) geschrieben
</Alert>

## Schnellanleitungs-App

Wenn Sie zum ersten Mal die OAuth-Authentifizierung mit den APIs von HubSpot verwenden, sollten Sie sich vorher unbedingt mit der in Node.js geschriebenen [OAuth 2.0 Schnellanleitungs-App](https://github.com/HubSpot/oauth-quickstart-nodejs) beschäftigen. Diese Beispiel-App ermöglicht einen schnellen Einstieg in die Verwendung von OAuth 2.0, da alle unten im [Abschnitt Abrufen von OAuth-Token](#getting-oauth-tokens) beschriebenen Schritte erläutert werden.

<div className="github-link">
  <img className="github-icon" src="https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/uie-icons/github.png" alt="GitHub icon" />

  <a href="https://github.com/HubSpot/oauth-quickstart-nodejs" target="_blank">
    Holen Sie sich die Schnellanleitungs-App.
  </a>
</div>

## Abrufen von OAuth-Token

### 1. Autorisierungs-URL erstellen und den Benutzer zum OAuth 2.0-Server von HubSpot weiterleiten

Wenn Sie einen Benutzer an den OAuth 2.0-Server von HubSpot verweisen, wird im ersten Schritt die Autorisierungs-URL erstellt. Dadurch wird Ihre App identifiziert und es werden die Ressourcen (Bereiche) definiert, auf die diese im Namen des Benutzers Zugriff anfordert. Die Abfrageparameter, die Sie als Teil einer Autorisierungs-URL übergeben können, werden unten in der Tabelle angezeigt. Weitere Informationen zu diesem Schritt finden Sie in der [Referenzdokumentation](/apps/legacy-apps/authentication/working-with-oauth).

<p className="table-key">
  Mit <span style={{ color: 'red' }}>\*</span> markierte Felder sind
  Pflichtfelder.
</p>

| Parameter                                           | Beschreibung                                                                                                                                                                   | Beispiel                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `client_id`<span style={{color:"red"}}>\*</span>    | Die Client-ID identifiziert Ihre App. Sie finden sie auf der Einstellungsseite Ihrer App.                                                                                      | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb`  |
| `scope`<span style={{color:"red"}}>\*</span>        | Die [Bereiche](/apps/legacy-apps/authentication/scopes#list-of-available-scopes), die Ihre Anwendung anfordert, getrennt durch URL-codierte Leerzeichen`%20`.                  | `oauth%20crm.objects.contacts.read`     |
| `redirect_uri`<span style={{color:"red"}}>\*</span> | Die URL, zu der der Benutzer weitergeleitet wird, nachdem er Ihre App für die angeforderten Bereiche autorisiert hat. **Für Produktionsanwendungen ist `https` erforderlich.** | `https://www.example.com/auth-callback` |
| `optional_scope`                                    | Die Bereiche, die für Ihre App optional sind und verworfen werden, wenn das ausgewählte HubSpot-Portal keinen Zugriff auf diese Produkte hat                                   | `automation`                            |
| `state`                                             | Ein eindeutiger Zeichenfolgenwert, der zur Aufrechterhaltung des Status des Benutzers verwendet werden kann, wenn er zurück zu Ihrer App weitergeleitet wird.                  | `WeHH_yy2irpl8UYAvv-my`                 |

Nachdem Sie Ihre URL erstellt haben, starten Sie den OAuth-Verknüpfungsprozess, indem Sie den Benutzer dorthin verweisen.

Die folgenden Code-Blöcke enthalten Beispiele für die Verwendung verschiedener Weiterleitungstypen:

**Mithilfe einer serverseitigen Weiterleitung:**

```js theme={null}
// Build the auth URL
const authUrl =
  "https://app.hubspot.com/oauth/authorize" +
  `?client_id=${encodeURIComponent(CLIENT_ID)}` +
  `&scope=${encodeURIComponent(SCOPES)}` +
  `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
  `&state=${encodeURIComponent(STATE)}`;

// Redirect the user
return res.redirect(authUrl);
```

**Mithilfe eines HTML-Links:**

```html theme={null}
<a
  href="https://app.hubspot.com/oauth/authorize?scope=contacts%20social&redirect_uri=https://www.example.com/auth-callback&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&state=xxxxxxxx"
  >Install</a
>
```

**Codierung eines zusätzlichen Status der Weiterleitung eines Benutzers:**

Einige Apps müssen den Benutzer möglicherweise an andere Orte weiterleiten. Beispielsweise kann eine App Benutzer auf verschiedene Subdomains ihrer Integration weiterleiten (z. B. `userA.integration.com` und `userB.integration.com`). Verwenden Sie dazu den `state`-Parameter, um weitere Informationen zum Benutzerstatus zu codieren:

1\. Generieren und speichern Sie einen Nonce-Wert für den state-Parameter.

2\. Speichern Sie den Status des Benutzers in einem lokalen Datenspeicher mit dem Nonce-Wert als dessen Schlüssel.

3\. Schließen Sie den Nonce-Wert als state-Parameter in der Autorisierungs-URL ein.

4\. Wenn sich der Benutzer authentifiziert und zu Ihrer Weiterleitungs-URL weitergeleitet wird, validieren Sie den state-Parameter und verwenden Sie ihn als Schlüssel, um den gespeicherten Benutzerstatus abzurufen.

5\. Leiten Sie den Benutzer von dort aus nach Bedarf weiter (z. B. durch erneutes Weiterleiten zu einer benutzerspezifischen URL).

### 2. HubSpot fordert Benutzer zur Einwilligung auf

HubSpot zeigt dem Benutzer ein Einwilligungsfenster an, in dem der Name Ihrer App und eine kurze Beschreibung der HubSpot API-Dienste angezeigt werden, für die eine Zugriffsberechtigung angefordert wird. Der Benutzer kann dann Zugriff auf Ihre App gewähren.

![Beispiel für einen Installationsprompt](https://www.hubspot.de/hubfs/Knowledge_Base_2023/%5BExample%5D%20Install%20Screen.png)

**Hinweis:** Der Benutzer, der die App installiert, muss Zugriff auf alle angeforderten Bereiche haben. Wenn er nicht die erforderlichen Zugriffsrechte besitzt, schlägt die Installation fehl und er wird zu einer Fehlerseite weitergeleitet. Sieht ein Benutzer diese Seite für einen Berechtigungsfehler, muss er einen Super-Admin bitten, die App zu installieren.

Ihre Anwendung funktioniert in dieser Phase nicht. Sobald der Zugriff gewährt ist, sendet der HubSpot OAuth 2.0-Server eine Anfrage an den in der Autorisierung der Autorisierungs-URL definierten Calback-URI.

### 3. Die OAuth-Serverantwort verarbeiten

Wenn der Benutzer die Aufforderung zur Einwilligung von Schritt 2 abgeschlossen hat, sendet der OAuth 2.0-Server eine `GET`-Anfrage an den in Ihrer Authentifizierungs-URL angegebenen Weiterleitungs-URI. Falls keine Fehler auftreten und der Benutzer die Zugriffsanfrage akzeptiert, wird die Anfrage mit einem angehängten `code`-Abfrageparameter an den Weiterleitungs-URI zurückgegeben. Gewährt der Benutzer keinen Zugriff, wird keine Anfrage gesendet.

**Beispiel:**

```js theme={null}
app.get("/oauth-callback", async (req, res) => {
  if (req.query.code) {
    // Handle the received code
  }
});
```

### 4. Autorisierungscode für Token austauschen

Nachdem Ihre App einen Autorisierungscode aus dem OAuth 2.0-Server empfangen hat, kann sie den Code für ein Zugriffs- und Aktualisierungstoken tauschen, indem eine im URL-Format codierte `POST`-Anfrage mit den unten aufgeführten Werten an `https://api.hubapi.com/oauth/v1/token` gesendet wird. Weitere Informationen zu diesem Schritt erhalten Sie in diesem [Referenzdokument](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).

| Parameter       | Beschreibung                                                         | Beispiel                                |
| --------------- | -------------------------------------------------------------------- | --------------------------------------- |
| `grant_type`    | Muss sein `authorization_code`                                       | `authorization_code`                    |
| `client_id`     | Die Client-ID Ihrer App                                              | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb`  |
| `client_secret` | Das Client-Geheimnis Ihrer App                                       | `7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d`  |
| `redirect_uri`  | Die Weiterleitungs-URI vom Autorisieren Ihrer App durch den Benutzer | `https://www.example.com/auth-callback` |
| `code`          | Der Autorisierungscode, der vom OAuth 2.0-Server empfangen wurde     | `5771f587-2fe7-40e8-8784-042fb4bc2c31`  |

**Beispiel:**

```js theme={null}
const formData = {
  grant_type: 'authorization_code',
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uri: REDIRECT_URI,
  code: req.query.code
};

request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => {
  // Handle the returned tokens
}
```

Der Text der Token-Antwort besteht aus JSON-Daten mit folgendem Format:

```json theme={null}
{
  "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
  "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
  "expires_in": 1800
}
```

<Alert type="warning" titleText="Hinweis:">
  Das Zugriffstoken läuft nach der Anzahl der Sekunden ab, die im `expires_in`-Feld der Antwort angegeben ist. Aktuell sind dies 30 Minuten. Details zum Erhalt eines neuen Zugriffs Token finden Sie weiter unten im Abschnitt [Aktualisieren von OAuth-Token](#refreshing-oauth-tokens).
</Alert>

## Verwenden von OAuth-Token

Sobald der Autorisierungscode-Prozess abgeschlossen ist, ist Ihre App autorisiert, Anfragen im Namen des Benutzers vorzunehmen. Stellen Sie dazu das Token als ein Bearer-Token im `Authorization`-HTTP-Header bereit. Spezifische Details dazu finden Sie im [Referenzdokument](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).

**Beispiel:**

```js theme={null}
request.get(
  "https://api.hubapi.com/contacts/v1/lists/all/contacts/all?count=1",
  {
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
  },
  (err, data) => {
    // Handle the API response
  }
);
```

<Alert type="warning" titleText="Hinweis:">
  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.
</Alert>

## Aktualisieren von OAuth-Token

OAuth-Zugriffstoken laufen in regelmäßigen Abständen ab. So ist sichergestellt, dass Angreifer bei einem kompromittierten Token nur für eine kurze Zeit Zugriff haben. Die Gültigkeitsdauer des Tokens in Sekunden wird im `expires_in`-Feld angegeben, wenn ein Autorisierungscode gegen ein Zugriffstoken getauscht wird.

Ihre App kann das empfangene Aktualisierungstoken gegen ein neues Zugriffstoken tauschen, indem eine im URL-Format codierte `POST`-Anfrage mit den unten aufgeführten Werten an `https://api.hubapi.com/oauth/v1/token` gesendet wird. Weitere Informationen zu diesem Schritt finden Sie in der [Referenzdokumentation](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).

\| Parameter | Beschreibung | Beispiel |
\| --- | --- | --- | --- |
\| `grant_type` | Muss `refresh_token` | `refresh_token` | sein. |
\| `client_id` | Die Client-ID Ihrer App | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb` |
\| `client_secret` | Das Client-Geheimnis Ihrer App | `7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d` |
\| `redirect_uri` | Die Weiterleitungs-URI vom Autorisieren Ihrer App durch den Benutzer | `https://www.example.com/auth-callback` |
\| `refresh_token` | Das Aktualisierungstoken, dass bei der Autorisierung Ihrer App durch den Benutzer empfangen wurde | `b9443019-30fe-4df1-a67e-3d75cbd0f726` |

**Beispiel:**

```js theme={null}
const formData = {
  grant_type: 'refresh_token',
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uri: REDIRECT_URI,
  refresh_token: REFRESH_TOKEN
};

request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => {
  // Handle the returned tokens
}
```

Der Text der Token-Antwort besteht aus JSON-Daten mit folgendem Format:

```json theme={null}
{
  "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
  "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
  "expires_in": 1800
}
```

Das neue Zugriffstoken kann dann verwendet werden, um Aufrufe im Namen des Benutzers vorzunehmen. Wenn das neue Token abläuft, können Sie anhand der gleichen Schritte ein neues abrufen.

## Verwandte Artikel

[Authentifizierungsmethoden in HubSpot](/apps/developer-platform/build-apps/authentication/overview)

[Arbeiten mit OAuth](/apps/legacy-apps/authentication/working-with-oauth)

[Verwalten von Token](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth)